How to install Odoo on macOS

Odoo does not ship a native macOS installer for local development in the same way many desktop apps do, so the most practical approach is to run Odoo Community from source.

This guide shows how to install Odoo on macOS with Homebrew, Postgres.app, Python, and PostgreSQL.

What you need

At the time of writing, Odoo 19 requires:

• Python 3.10 or later
• PostgreSQL 13 or later
• Node.js and rtlcss for right-to-left assets
• wkhtmltopdf 0.12.6 if you want proper PDF headers and footers

1. Install Homebrew

If Homebrew is not installed yet, install it first:

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

Verify it:

brew --version

2. Install basic dependencies

Install Apple Command Line Tools:

xcode-select --install

Then install Git, Python, and Node.js:

brew install git python node

Verify Python and pip:

python3 --version
pip3 --version

3. Install PostgreSQL

Odoo officially recommends using Postgres.app on macOS.

Download and install Postgres.app from:

https://postgresapp.com/

After installation, add PostgreSQL CLI tools to your shell:

echo 'export PATH="/Applications/Postgres.app/Contents/Versions/latest/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify PostgreSQL:

psql --version

4. Create a PostgreSQL user

Odoo does not allow connecting as the default postgres user, so create a separate PostgreSQL user with your current macOS username:

createuser -d -R -S $USER
createdb $USER

This setup usually lets Odoo connect locally without a password because the PostgreSQL user matches your macOS username.

5. Clone Odoo Community source code

Clone the official Odoo repository. This example uses branch 19.0:

git clone --branch 19.0 --depth 1 https://github.com/odoo/odoo.git
cd odoo

6. Create a virtual environment

Using a virtual environment keeps Odoo’s Python packages isolated from the rest of your system:

python3 -m venv .venv
source .venv/bin/activate

Upgrade the packaging tools and install Odoo’s Python requirements:

pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

7. Install rtlcss

Odoo uses rtlcss for right-to-left language support such as Arabic and Hebrew.

Install it globally with npm:

npm install -g rtlcss

Verify it:

rtlcss --version

8. Install wkhtmltopdf for PDF reports

If you need invoice or report PDFs with proper headers and footers, install wkhtmltopdf version 0.12.6 manually.

You can get it from the wkhtmltopdf project releases:

https://github.com/wkhtmltopdf/packaging/releases

This step is optional for basic development, but many report features depend on it.

9. Create an Odoo database

Create a database for Odoo:

createdb odoo19

10. Run Odoo

Start Odoo from the project directory:

python3 odoo-bin --addons-path=addons -d odoo19

Once the server starts, open this URL in your browser:

http://localhost:8069

You should see the Odoo database setup screen.

11. Run Odoo with PyCharm

If you use PyCharm, you can run Odoo directly from the IDE instead of starting it manually from Terminal.

Open the project

Open the cloned odoo folder in PyCharm.

Configure the Python interpreter

Go to PyCharm > Settings > Project > Python Interpreter and select the virtual environment you created earlier:

/path/to/odoo/.venv/bin/python

If the interpreter is not listed, add it manually and point PyCharm to the .venv Python binary.

Create a run configuration

Create a new Python run configuration with these values:

• Name: Odoo
• Script path: /path/to/odoo/odoo-bin
• Working directory: /path/to/odoo
• Parameters: --addons-path=addons -d odoo19
• Python interpreter: /path/to/odoo/.venv/bin/python

If you want PyCharm to show logs immediately in the built-in console, keep Run with Python Console disabled and use the standard run output.

Start Odoo from PyCharm

After saving the run configuration, click the Run button in PyCharm.

Odoo should start the same way it does from Terminal, and you can open:

http://localhost:8069

Optional: enable debug mode

If you want to debug Odoo code in PyCharm, use the same run configuration and click Debug instead of Run. This lets you set breakpoints in controllers, models, and custom modules.

12. Common useful commands

Start Odoo again later:

cd /path/to/odoo
source .venv/bin/activate
python3 odoo-bin --addons-path=addons -d odoo19

Create another database:

createdb mynewdb

List PostgreSQL databases:

psql -l

Stop Odoo:

Press Ctrl+C in the terminal where Odoo is running.

Troubleshooting

PyCharm cannot find modules

Usually this means PyCharm is using the wrong interpreter. Make sure the project interpreter points to:

/path/to/odoo/.venv/bin/python

PyCharm starts but Odoo does not open

Double-check the run configuration:

• Script path should point to odoo-bin
• Working directory should be the Odoo project root
• Parameters should include --addons-path=addons -d odoo19

psql: command not found

Postgres.app is installed, but its CLI tools are not in your PATH. Add this line to ~/.zshrc and reload the shell:

export PATH="/Applications/Postgres.app/Contents/Versions/latest/bin:$PATH"

ModuleNotFoundError or pip install failures

Make sure the virtual environment is activated:

source .venv/bin/activate

Then reinstall dependencies:

pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

PDF reports are broken

This usually means wkhtmltopdf is missing or the version is wrong. Odoo expects version 0.12.6 for proper header and footer support.

Final words

Installing Odoo on macOS is straightforward once Python, PostgreSQL, and the required tools are in place. For local development, the source install method gives you the most flexibility and matches Odoo’s official documentation for macOS.