---
title: macOS Development Setup
description: Complete guide to setting up your macOS development environment for Chatwoot contribution.
sidebarTitle: macOS Setup
---

# macOS Development Setup

This guide will help you set up your macOS development environment for contributing to Chatwoot. Open Terminal app and run the following commands.

## Installing the Standalone Command Line Tools

Open Terminal app and run:

```bash
xcode-select --install
```

This installs essential development tools including Git, GCC, and other command line utilities.

## Install Homebrew

Homebrew is the missing package manager for macOS:

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
```

After installation, add Homebrew to your PATH (if not automatically added):

```bash
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
```

## Install Git

```bash
brew update
brew install git
```

Configure Git with your information:

```bash
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```

## Install Ruby Version Manager

Choose between RVM or rbenv for managing Ruby versions.

### Option 1: Install RVM (Recommended)

```bash
curl -L https://get.rvm.io | bash -s stable
source ~/.rvm/scripts/rvm
```

### Option 2: Install rbenv (Alternative)

```bash
brew install rbenv ruby-build
echo 'eval "$(rbenv init -)"' >> ~/.zshrc
source ~/.zshrc
```

## Install Ruby

Chatwoot APIs are built on Ruby on Rails. You need to install Ruby 3.2.2.

### If using RVM:

```bash
rvm install ruby-3.2.2
rvm use 3.2.2 --default
source ~/.rvm/scripts/rvm
```

### If using rbenv:

```bash
rbenv install 3.2.2
rbenv global 3.2.2
```

<Info>
rbenv identifies the ruby version from `.ruby-version` file on the root of the project and loads it automatically.
</Info>

Verify Ruby installation:

```bash
ruby --version
# Should output: ruby 3.2.2
```

## Install Node.js

Chatwoot requires Node.js version 20:

```bash
brew install node@20
```

If you need to link Node.js 20:

```bash
brew link node@20
echo 'export PATH="/opt/homebrew/opt/node@20/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

Verify Node.js installation:

```bash
node --version
# Should output: v20.x.x
```

## Install pnpm

We use `pnpm` as our package manager for better performance:

```bash
brew install pnpm
```

Verify pnpm installation:

```bash
pnpm --version
```

## Install PostgreSQL

The database used in Chatwoot is PostgreSQL.

### Option 1: PostgresApp (Recommended)

1. Download and install PostgresApp from [https://postgresapp.com](https://postgresapp.com)
2. This is the easiest way to get started with PostgreSQL on macOS
3. Follow the setup instructions on their website

### Option 2: Homebrew Installation

```bash
brew install postgresql@14
```

Start PostgreSQL service:

```bash
brew services start postgresql@14
```

Create a PostgreSQL user:

```bash
createuser -s postgres
```

Connect to PostgreSQL to verify installation:

```bash
psql postgres
# Type \q to exit
```

## Install Redis Server

Chatwoot uses Redis server for agent assignments and reporting:

```bash
brew install redis
```

Start the Redis service:

```bash
brew services start redis
```

Verify Redis installation:

```bash
redis-cli ping
# Should output: PONG
```

## Install ImageMagick

Chatwoot uses ImageMagick library to resize images for previews and thumbnails:

```bash
brew install imagemagick
```

Verify ImageMagick installation:

```bash
convert --version
```

## Install Additional Dependencies

Install other useful development tools:

```bash
# Install Yarn (alternative to pnpm if needed)
brew install yarn

# Install SQLite (for testing)
brew install sqlite

# Install libvips (for image processing)
brew install libvips
```

## Install Docker (Optional)

For development and testing with containers:

```bash
# Install Docker Desktop
brew install --cask docker
```

Or download Docker Desktop from [https://www.docker.com/products/docker-desktop/](https://www.docker.com/products/docker-desktop/).

## Environment Verification

Verify all installations are working:

```bash
# Check versions
ruby --version        # Should be 3.2.2
node --version         # Should be v20.x.x
pnpm --version        # Should show pnpm version
psql --version        # Should show PostgreSQL version
redis-cli --version   # Should show Redis version
convert --version     # Should show ImageMagick version
git --version         # Should show Git version
```

## Configure Shell Environment

Add useful aliases to your shell configuration file (`~/.zshrc` for Zsh):

```bash
# Add to ~/.zshrc
echo '# Chatwoot Development Aliases' >> ~/.zshrc
echo 'alias cw-server="bundle exec rails server"' >> ~/.zshrc
echo 'alias cw-console="bundle exec rails console"' >> ~/.zshrc
echo 'alias cw-test="bundle exec rspec"' >> ~/.zshrc
echo 'alias cw-migrate="bundle exec rails db:migrate"' >> ~/.zshrc

# Reload shell configuration
source ~/.zshrc
```
## Troubleshooting Common Issues

<Accordion title="Command line tools installation fails">
**Solution**: Update macOS to the latest version and try again. You can also download Xcode from the App Store.
</Accordion>

<Accordion title="Homebrew installation permission errors">
**Solution**: 
```bash
sudo chown -R $(whoami) /opt/homebrew
```
</Accordion>

<Accordion title="Ruby installation fails with RVM">
**Solution**: 
```bash
# Install missing dependencies
brew install openssl readline libyaml
rvm reinstall 3.2.2 --with-openssl-dir=$(brew --prefix openssl)
```
</Accordion>

<Accordion title="PostgreSQL connection refused">
**Solution**: 
```bash
# Restart PostgreSQL
brew services restart postgresql@14

# Check if it's running
brew services list | grep postgresql
```
</Accordion>

<Accordion title="ImageMagick installation issues">
**Solution**: 
```bash
# If you encounter issues, try:
brew uninstall imagemagick
brew install imagemagick
```
</Accordion>

## Getting Help

If you encounter issues:

- **Common Errors**: Check [Common Errors](/contributing/project-setup/common-errors)
- **Discord Community**: Join our [Discord](https://discord.com/invite/cJXdrwS)
- **GitHub Issues**: [Create an issue](https://github.com/chatwoot/chatwoot/issues)

---

Your macOS development environment is now ready for Chatwoot development! 🚀