🛠️

Odoo on macOS: A Step-by-Step Guide

Odoo Enterprise Development Environment on macOS (Clean Install + PyCharm Setup)

🔧 Step 1: Install Xcode Command Line Tools

Open your terminal and run:

xcode-select --install

🍺 Step 2: Install Homebrew

Homebrew is the package manager for macOS. To install it, run:

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

For more details, visit the Homebrew official website.

🛠️ Step 3: Add Homebrew to Your PATH

After installing Homebrew, you need to add it to your shell environment so you can use the brew command in the terminal. Run the following commands:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/YOUR_MAC_USERNAME/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"'

⚠️

Replace YOUR_MAC_USERNAME with your actual macOS username

🐍 Step 4: Install Python

Odoo requires a specific version of Python depending on which version of Odoo you're installing.

💡

You can find the required Python version in the official Odoo documentation. To check for a different version (e.g., Odoo 18), simply replace 16.0 in the URL with the desired version:

https://www.odoo.com/documentation/16.0/administration/on_premise/source.html

Then go to the Prepare section in the sidebar, and click on Python.

To install the correct Python version, replace XX below with the Python version number recommended for your Odoo version:

brew install python@3.XX

‼️

Using the wrong Python version can lead to compatibility issues when installing dependencies.

🗂️ Step 5: Install wkhtmltopdf

Odoo needs a specific patched version of wkhtmltopdf for PDF reports to work correctly.

Go to the official downloads page:
https://wkhtmltopdf.org/downloads.html

Download the installer or package for your OS and install it following the instructions on the site.

📁 Step 6: Create Working Directories

💡

Example of Odoo project structure:

work/
├── odooxx/
│   ├── odoo-xx/
│   │   ├── odooxx/
│   │   ├── odooxxenv/
│   │   └── environment/
│   ├── odoo-enterprise/
│   └── odooxx-custom-addons/
│       └── extra/
└── odooxx-work/
    ├── addons/
    │   ├── odoo-enterprise -> ../../odooxx/odoo-enterprise
    │   └── extra -> ../../odooxx/odooxx-custom-addons/extra
    ├── etc/
    └── tools/

Now let’s create a folder structure for your Odoo project. You can create it anywhere — in this example, we’ll place it in the home directory.

Replace XX with your Odoo version (e.g. 16, 17, 18):

mkdir -p ~/work/{odoo-XX,odoo-enterprise,odooXX-custom-addons/extra}

This will create the following directories:

odoo-XX: your main Odoo (community) source;
odoo-enterprise: for enterprise source code (if using Odoo Enterprise);
odooXX-custom-addons/extra: for custom modules.

🐍 Step 7: Create and Activate a Python Virtual Environment

Navigate to your main Odoo directory and create a virtual environment using the appropriate Python version:

cd ~/work/odoo-XX
python3.XX -m venv odooXXenv
source odooXXenv/bin/activate

💡

Replace XX to your actual versions and use correct path.

Once activated, your terminal prompt will change — indicating that the virtual environment is active. All Python packages installed from now on will be isolated within this environment:

(odooXXenv) YOUR_MAC_USERNAME odoo-XX %

🧬 Step 8: Install Git and Clone Odoo Source Code

First, install Git (if you haven't already):

brew install git

Then, clone the official Odoo repository from GitHub. Replace XX with your target Odoo version (e.g. 17.0, 18.0) and adjust the folder name accordingly:

git clone https://github.com/odoo/odoo.git -b XX.0 --single-branch --depth 1 odoo-XX

💡

This will download only the latest commit of the selected branch (--depth 1), which speeds up the cloning process and saves space.

🐘 Step 9: Install PostgreSQL

Install PostgreSQL via Homebrew:

brew install postgresql

⚠️

You don’t need to run PostgreSQL right now if you're not planning to use it locally. In this setup, it's installed only to satisfy Python package dependencies (like psycopg2), which require PostgreSQL libraries during installation.

📦 Step 10: Install Essential Python Packages Manually

Before installing Odoo's full list of dependencies, it’s a good idea to install a few core Python packages manually — especially ones that may cause build errors if missing.

Replace XX with your Python version (e.g. 3.9, 3.10):

python3.XX -m pip install wheel setuptools psycopg2-binary

📄 Step 11: Install Python Dependencies from requirements.txt

Navigate to your Odoo source folder and install all required Python packages (replace XX with your Odoo and Python version (e.g. 16, 3.9).):

cd ~/work/odoo-XX
python3.XX -m pip install -r requirements.txt

This will install all core dependencies listed by Odoo for your version.

⚠️

Make sure your virtual environment is activated before running this command.

💼 Step 12: Get Access to the Odoo Enterprise Codebase

If you're working with the Enterprise edition of Odoo, you'll need access to the private Enterprise repository:

👉 https://github.com/odoo/enterprise

⚠️

If you see a 404 error, it means your GitHub account doesn’t have access.

Ask your colleague to:

Invite you to the Odoo GitHub organization, or
Share the Enterprise source code with you as a .zip archive.

📥 Step 13: Add Odoo Enterprise Code to Your Project

Navigate to your odoo-enterprise directory:

cd ~/work/odoo-enterprise

Then either:

Option 1: Clone from GitHub (if you have access):

git clone --branch XX.0 --single-branch --depth 1 https://github.com/odoo/enterprise.git enterpriseXX

💡

Replace XX to your actual versions.

Option 2: Use .zip archive (if you don’t have access):

Unzip the archive and move its contents to the ~/work/odoo-enterprise directory manually.

💻 Step 14: Before You Start: Install PyCharm (Recommended IDE)

For this guide, we’ll be using PyCharm as the development environment — specifically the version for Apple Silicon (M1/M2/M3 chips):

👉 Download PyCharm for Apple Silicon

⚠️

If you're using an Intel-based Mac, make sure to choose the Intel version instead.

💡

You can use a different IDE (like VS Code or Sublime), but the configuration steps (e.g. interpreter setup, project structure) may differ.

🧱 Step 15: Create a New Project in PyCharm

Now let’s set up your Odoo project in PyCharm.

1. Open PyCharm and create a new project:

Go to File → New Project;
In the left panel, select "Pure Python";
Name your project something like odooXX (replace XX with your version, e.g. odoo16);
Set Location to the directory where your Odoo project is located — for example:

~/work/odooXX

2. Set up the interpreter:

Under "Python Interpreter", browse and select the Python interpreter from the virtual environment you created earlier:

~/work/odoo-XX/odooXXenv/bin/python3.XX

3. Finalize:

Under "Python Interpreter", browse and select the Python interpreter from the virtual environment you created earlier:

Click "OK", then "Create".

PyCharm will create and open your new project.

🐳 Step 16: Set Up PostgreSQL in Docker (for Odoo)

📁 1. Create docker-compose.yaml in your project root

In the root folder of your project (e.g. ~/work/odooXX), create a file named docker-compose.yaml and paste the following content:

version: "3.3"

services:
  odooXX_db:
    container_name: odooXX_db
    image: postgres
    env_file:
      - environment/database.env
    ports:
      - "5432:5432"
    volumes:
      - odooXX_db_volume:/var/lib/postgresql/data

volumes:
  odooXX_db_volume: {}

💡

Replace XX to your actual versions.

This setup creates a PostgreSQL container accessible on port 5432 and persists the database in a named volume.

📁 2. Create the environment/database.env file

Inside your project, create a folder named environment, and inside it, create a file called database.env with the following contents:

POSTGRES_USER=odoo
POSTGRES_PASSWORD=odoo
POSTGRES_DB=postgres

📁 3. Start PostgreSQL using Docker

In the PyCharm terminal (or any terminal inside your project root), run:

docker-compose up

💡

This will start the PostgreSQL container in the background and expose it on localhost:5432.

⚙️ Step 17: Create odoo.conf Configuration File

In the root folder of your project (e.g. ~/work/odooXX), create a folder named etc and create the configuration file odoo.conf inside the folder with the following content:

[options]
addons_path = /Users/YOUR_MAC_USERNAME/work/odoo-XX/odoo/addons/,/Users/YOUR_MAC_USERNAME/work/odoo-enterprise/enterprise-XX/,/Users/YOUR_MAC_USERNAME/work/odooXX-custom-addons/extra/
admin_passwd = parole123
db_host = localhost
db_port = 5432
db_user = odoo
db_password = odoo
cpu_time_limit = 15000
db_name = False
list_db = True
log_db = False
log_db_level = warning
limit_time_real = 10000
limit_memory_hard = 0
bin_path = /usr/local/bin/wkhtmltopdf

💡

Replace YOUR_MAC_USERNAME with your actual Mac username;
Replace all XX with your Odoo version number (e.g. 17, 18);
admin_passwd is the master password to manage databases in Odoo. Change it to a strong password if needed;
Make sure paths correspond to your actual folder structure;
bin_path points to wkhtmltopdf executable — ensure it’s installed at that location or update the path accordingly.

🔗 Step 18: Create addons Folder and Set Symlinks

In the root folder of your Odoo project (e.g. ~/work/odooXX), create a folder named addons and create symbolic links (symlinks) to your addons folders:

ln -s /Users/YOUR_MAC_USERNAME/work/odoo-enterprise/enterprise-XX ~/work/odooXX/addons/
ln -s /Users/YOUR_MAC_USERNAME/work/odooXX-custom-addons/extra ~/work/odooXX/addons/

💡

! addons/extra is folder for custom addons !

Replace YOUR_MAC_USERNAME with your Mac username;
Replace XX with your Odoo version (e.g. 17, 18);
Adjust paths if your folders are located elsewhere.

▶️ Step 19: Create Odoo Run/Debug Configuration in PyCharm

Open PyCharm and open your Odoo project;
In the upper right corner, click on the dropdown menu (usually says "Current File") and select Edit Configurations...;
Click Add New Configuration, then choose Python;
Fill in the fields as follows:
- Name: odoo-bin
- Script path: /Users/YOUR_MAC_USERNAME/work/odooXX/odoo/odoo-bin
- Parameters (under Script path): -c /Users/YOUR_MAC_USERNAME/work/odooXX/etc/odoo.conf --dev=all
- Working directory: /Users/YOUR_MAC_USERNAME/work/odooXX

⚠️

Paths shown here are examples and may differ depending on your setup and folder structure.

Click OK to save the configuration.

▶️ Step 20: Add Odoo Community Modules Folder to Project Structure in PyCharm

To make it easier to search and navigate the Odoo code in PyCharm and Finder, add the addons folder to your project structure:

Open PyCharm;
Go to PyCharm → Settings;
Navigate to Project Structure;
Click Add Content Root;
Select the folder with Odoo community modules:

/Users/YOUR_MAC_USERNAME/work/odooXX/addons/