Local Odoo Development Setup on Mac

This article provides a step-by-step guide to setting up a Local Odoo development environment on a Mac. Follow these instructions to ensure a smooth development experience.

Prerequisites

• Access to the Odoo repository you want to work with.

• Docker for Mac installed. Refer to the Docker documentation for installation: Docker Installation Guide.

• Homebrew installed. For installation details, visit: Homebrew Homepage.

Clone the Odoo Repository

Clone the Odoo repository you want to work with. Execute the following command in your terminal:

git clone <github url>
# Replace <github url> with the actual URL of the Odoo repository you want
# to work on locally. The cloned folder becomes your "project directory"
# and is the place where every following `odoo ...` command must be run.

Replace  with the actual URL of the Odoo repository you want to work on locally.

Install Zodoo

Zodoo is a lightweight Docker framework for Odoo. The installer fetches the script from the official Odoo-Ninjas GitHub repo and pipes it into bash, registering the global odoo CLI on your machine via pipx.

bash <(curl -fsSL https://raw.githubusercontent.com/Odoo-Ninjas/zodoo/refs/heads/main/install.sh)
# Downloads and executes the official Zodoo installer.
# By default it uses Python 3.9 (which ships with Xcode on macOS).

If you need to pin Zodoo to a specific Python version (recommended for newer Odoo releases that drop 3.9 support), reinstall it with pipx pointing to a pyenv-managed interpreter:

pipx reinstall wodoo --python ~/.pyenv/versions/3.12.13/bin/python3
# Reinstalls the underlying `wodoo` package using a different Python runtime.
# Useful when your Odoo version requires Python >= 3.10.

Configure Odoo Development Settings

Navigate to the cloned Odoo repository in your IDE and open a terminal at its root. The following commands set up the local development environment.

odoo setting DEVMODE=1 -s
# Enables development mode (extra logging, less aggressive caching, hot reload hooks).
# The -s flag stores the setting *system-wide* across every Zodoo project on this
# machine — handy on a dev machine. It might require sudo.

odoo setting ODOO_DEMO=1 # Tells Zodoo to load Odoo's demo data when the database is initialised.
# Great for testing; turn it off (=0) for production-like setups.

odoo reload
# Regenerates the docker-compose file and the project settings under
# ~/.odoo/settings.<project-name> by parsing the manifest files of your modules
# and resolving their dependencies. Run this any time you change settings or modules.

odoo build
# Builds the Docker images defined by the freshly generated docker-compose
# (Odoo image, Postgres, etc.). Equivalent to `docker compose build`.
# Can take several minutes on the first run.

odoo up -d
# Starts all containers in detached mode (-d = background).
# After this command, Odoo, Postgres and any side services are running.

To reset the database for demo purposes (drops the DB, recreates it, loads demo data if ODOO_DEMO=1):

odoo -f db reset
# -f = force (skip the interactive "are you sure?" prompt).
# Useful when you want a clean slate during development.

If you need to restore a customer database from a dump:

odoo -f restore odoo-db <dump-path>
# Example:
# odoo -f restore odoo-db ~/odoo_dumps/customer.odoo.20260425000552.dump.gz
# Restores the given dump into the project's Postgres container.

⚠️ Important — Applying code changes

Whenever you modify module code (Python, XML views, security rules, data files, etc.), the running Odoo instance won't reflect those changes until the modules are re-loaded into the database. To apply them, run:

odoo update
# Installs/updates the Odoo modules listed in the MANIFEST of your project.
# Equivalent to running Odoo with -u <module> -i <module> for everything declared.
# Run this after pulling new code or after `db reset`.

💡 Tips

• To update only a specific module (faster than a full update), use: odoo update <module_name>

• Pure Python changes can often be picked up live by running Odoo in dev mode (odoo dev) without a full update, but structural changes (models, fields, views, security, data) always require odoo update.

• If a change still doesn't appear after updating, do a hard refresh in the browser (⌘ + Shift + R) to bypass Odoo's asset cache.

Problems that might occur

If you are encountering issues due to a previous installation of Wodoo (📦 Installing /Users/David/.odoo/images/wodoo/src via pipx... Unable to parse package spec: /Users/.odoo/images/wodoo/src), run the following command to clean up:

rm -Rf ~/.odoo/images
# Removes Zodoo's local image/source cache so the next `odoo` command
# downloads a fresh copy. Safe to run — no project data lives here.

If you receive an error related to syncing folders (File "/Users/.odoo/images/wodoo/src/wodoo/tools.py", line 1153, in rsync_progress_param version = tuple(map(int, match.groups())) ^^^^^^^^^^^^ AttributeError: 'NoneType' object has no attribute 'groups')
first install rsync:

brew install rsync
# Installs an up-to-date rsync. Zodoo uses it to sync source folders
# into the Odoo container; the macOS default is too old to be parsed correctly.

To set the Python version, use the following command:

odoo setting ODOO_PYTHON_VERSION 3.12
# Tells Zodoo which Python interpreter the Odoo container should use.
# Run `odoo reload` and `odoo build` afterwards so the change takes effect.

Conclusion

By following these steps, you should have a fully functioning Local Odoo development setup on your Mac. Remember the typical workflow after any change:

1. odoo reload — regenerate compose/settings.

2. odoo build — rebuild images if Dockerfiles or dependencies changed.

3. odoo up -d — (re)start containers.

4. odoo update — apply module changes.

5. odoo status — check the running URL and credentials.