Como configurar um ambiente de desenvolvimento Odoo 19 (2026)

By the end of this recipe, your local machine will run a fully working Odoo 19 development environment with Python virtualenv, Docker Postgres, VS Code with debugger, hot-reload on file save, and the ability to switch between Odoo 17/18/19 with a single command. Skill required: comfortable with Linux/macOS terminal (Windows works via WSL2). Time required: 90 minutes for the first version, 30 minutes for each additional version. ECOSIRE engineers use this exact setup, and the recipe below is what we onboard new hires with.

The trap most teams fall into: trying to run the official Odoo Docker images for development. The official images are great for production deployments but slow for dev (no hot reload, painful debugger attach, slow IO on the filestore mount). The recipe below uses Docker only for Postgres and runs Odoo natively in Python for fast iteration.

What you will need

• OS: macOS 14+, Ubuntu 22.04+, or Windows 11 with WSL2 + Ubuntu 22.04.
• Docker Desktop for Postgres.
• Python 3.10 or 3.11 (Odoo 19 supports both; 3.11 is faster).
• VS Code with Python + Odoo extensions.
• Git.
• Time: 90 minutes first version, 30 min per additional.

Step-by-step

1. Install system dependencies

On Ubuntu/WSL2:

sudo apt update && sudo apt install -y python3.11 python3.11-venv python3-pip \
    build-essential libxslt1-dev libzip-dev libldap2-dev libsasl2-dev \
    libpq-dev libjpeg-dev wkhtmltopdf nodejs npm git
sudo npm install -g rtlcss

On macOS:

brew install [email protected] postgresql node wkhtmltopdf
npm install -g rtlcss

Verification: python3.11 --version returns 3.11.x. wkhtmltopdf --version returns 0.12.6 (qt-patched).

2. Clone Odoo source

mkdir -p ~/dev/odoo && cd ~/dev/odoo
git clone --depth 1 --branch 19.0 https://github.com/odoo/odoo
git clone --depth 1 --branch 19.0 https://github.com/odoo/enterprise   # if you have access
mkdir custom-addons

Use --depth 1 to clone shallow — saves 4 GB of git history you don't need.

Verification: ls odoo/addons | wc -l returns ~200 modules.

3. Create the virtualenv

cd ~/dev/odoo
python3.11 -m venv venv
source venv/bin/activate
pip install --upgrade pip wheel
pip install -r odoo/requirements.txt
pip install ipdb watchdog python-dotenv

watchdog enables hot-reload via --dev flag. ipdb is a much better debugger than the default pdb.

Verification: pip list | grep odoo-19 returns nothing (Odoo isn't installed as a package; we run it from source).

4. Start the Postgres container

~/dev/odoo/docker-compose.yml:

version: '3.8'
services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: odoo
      POSTGRES_PASSWORD: odoo
    ports:
      - "5433:5432"   # 5433 to avoid clash with system Postgres
    volumes:
      - odoo-pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U odoo"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  odoo-pgdata:

docker compose up -d. Verification: docker exec -it $(docker ps -qf 'name=postgres') psql -U odoo -c "SELECT 1" returns 1.

5. Write the dev config

~/dev/odoo/odoo.dev.conf:

[options]
addons_path = /home/you/dev/odoo/odoo/addons,/home/you/dev/odoo/enterprise,/home/you/dev/odoo/custom-addons
data_dir = /home/you/dev/odoo/data
db_host = localhost
db_port = 5433
db_user = odoo
db_password = odoo
xmlrpc_port = 8069
log_level = info
dev_mode = reload,qweb,xml

dev_mode = reload,qweb,xml enables hot-reload of Python files, QWeb templates, and XML views. Dev workflow: save file in VS Code, Odoo auto-reloads, refresh browser, see change.

Verification: starting Odoo in step 6 reads this config without errors.

6. Create launch script

~/dev/odoo/run.sh:

#!/bin/bash
set -e
cd "$(dirname "$0")"
source venv/bin/activate
exec python odoo/odoo-bin -c odoo.dev.conf "$@"

chmod +x run.sh. Now ./run.sh -i base -d test_db --stop-after-init initializes a database. Verification: ./run.sh -d test_db --no-http boots without errors and creates the database.

7. Configure VS Code

~/dev/odoo/.vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Odoo Debug",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/odoo/odoo-bin",
      "args": ["-c", "${workspaceFolder}/odoo.dev.conf", "-d", "test_db"],
      "python": "${workspaceFolder}/venv/bin/python",
      "console": "integratedTerminal",
      "justMyCode": false
    },
    {
      "name": "Odoo Tests",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/odoo/odoo-bin",
      "args": ["-c", "${workspaceFolder}/odoo.dev.conf", "-d", "test_db",
                "--test-enable", "-i", "${input:moduleName}", "--stop-after-init"],
      "python": "${workspaceFolder}/venv/bin/python",
      "console": "integratedTerminal"
    }
  ],
  "inputs": [
    {"id": "moduleName", "type": "promptString", "description": "Module to test"}
  ]
}

Install VS Code extensions: Python (Microsoft), Odoo Snippets (Trinh Anh Ngoc), GitLens.

Verification: F5 launches Odoo in the debugger. Setting a breakpoint in any Python file and triggering the code path stops execution there.

8. Add multi-version support

For switching between Odoo versions:

mkdir -p ~/dev/odoo-17 ~/dev/odoo-18 ~/dev/odoo-19
# Repeat the clone + venv + config in each

Use direnv (brew install direnv) to auto-activate the right venv per directory:

# ~/dev/odoo-19/.envrc
source venv/bin/activate

Now cd ~/dev/odoo-19 automatically activates the correct venv. Verification: cd ~/dev/odoo-17 && python --version shows 3.10 (or whichever was used for v17).

Common mistakes

• Mixing system Python with venv Python. Always activate venv first; otherwise pip install pollutes your system.
• Forgetting to expose port 5433 from Docker. Connection refused if Odoo tries to connect to localhost:5432 (system PG).
• dev_mode=all. Sounds like a good idea but enables features that slow performance. Stick to reload,qweb,xml.
• Running Odoo as root in the venv. Some packages (psycopg2-binary) install user-only files and fail when run as root.
• Skipping wkhtmltopdf "qt patched". Reports look broken without the patched build.

Going further

Pre-commit hooks: install pre-commit and configure black, isort, flake8, pylint-odoo to run on every commit. Catches style issues before review. .pre-commit-config.yaml lives at the repo root with hooks for each tool. CI also runs the same checks on PR.

Odoo Editor extension: install the official Odoo VS Code extension for better autocomplete on Odoo APIs. Provides snippets for models.Model, fields.Char, _inherit, and others. Significantly speeds up boilerplate writing.

Browser extension: install "Odoo Debug" Chrome extension for one-click developer mode toggle. Saves 5 seconds every time you toggle dev mode (which is often during active debugging).

LiveReload: pair the --dev=reload flag with browser auto-refresh extension to refresh Chrome on every Python file save. Closer to a true hot-reload experience.

SQL client: install DBeaver or PostgreSQL VS Code extension for direct DB access. Useful for quick queries that would otherwise require opening odoo-bin shell.

Profiling tools: py-spy for CPU profiling without modifying code. Attach to a running Odoo process and get a live flame graph.

Log aggregation: pipe Odoo logs to a local Loki + Grafana stack for searchable history. Especially useful when debugging issues that span many requests.

Mock external services: for development without real Stripe/SendGrid/etc, use responses library to mock HTTP calls in dev mode. Avoids hitting test billing APIs constantly.

Branch-per-feature workflow: each new feature in its own git branch + database. Avoids polluting your main dev DB.

Odoo 19 Python 3.11 vs 3.12: 3.12 is supported but slightly more risk because it's newer. 3.11 is the safer default for production-bound development. Run tests on both if possible.

OpenUpgrade integration: clone OCA/OpenUpgrade into your dev environment for testing version migrations without leaving the dev workflow.

Dev-mode databases: keep a "dev_clean" database that's a fresh install for reproducing issues, separate from your "dev_work" database with all your test data.

For full development environment standardization including pre-commit, CI templates, and team onboarding playbooks, ECOSIRE Odoo support provides developer enablement engagements. Pair this with how to write an Odoo unit test.

Frequently Asked Questions

Do I need Docker for development?

Only for Postgres. Running Odoo itself in Docker for dev makes hot reload painful and the debugger flaky. Native Python execution is significantly faster, especially on macOS where Docker IO is slow.

Can I run multiple Odoo versions simultaneously?

Yes — use different ports (xmlrpc_port) and different Postgres databases. The Docker compose covers Postgres; run different odoo-bin processes for each version. Tag your terminal sessions clearly so you don't accidentally run pip install in the wrong venv.

What about Odoo.sh?

Odoo.sh is great for prod hosting and CI but slower for dev iteration than local. Most ECOSIRE engineers develop locally and push to Odoo.sh for QA. The local-first workflow lets you iterate in seconds; Odoo.sh build cycles are minutes.

How do I get Enterprise modules without a subscription?

You need a paid Enterprise license to legally use them. For dev environments, Odoo grants partner-tier access. Without it, you're limited to Community.

Can I share my dev DB with my team?

Use pg_dump | pg_restore to share a snapshot. For real-time sharing, use a shared Postgres on a dev server with each developer having their own schema. The shared DB drifts quickly though; most teams find isolated local DBs easier.

What about WSL2 specifically on Windows?

Works perfectly. Install Ubuntu via WSL2, follow the Linux instructions verbatim. Mount your code at /mnt/c/... if you want VS Code on Windows to see it; but the file system performance is much better if you keep code inside the WSL filesystem at /home/<user>/dev.

How do I keep Python dependencies in sync across team?

pip freeze > requirements-dev.txt and commit it. Each new team member runs pip install -r requirements-dev.txt after cloning.

What about Apple Silicon (M1/M2/M3) compatibility?

All Python and Odoo dependencies work natively on ARM. The Postgres image is multi-arch. wkhtmltopdf needs the ARM build (download from wkhtmltopdf releases page).

How do I debug into Odoo core?

Set justMyCode: false in launch.json. Then F5; breakpoints in Odoo core (/opt/odoo/odoo/...) hit. Useful for understanding how core methods behave.

Should I version-control the dev Postgres data?

No — dev DBs are throwaway. Use a script to recreate from scratch with seed data when needed. Keeps the team's local environments aligned.

What VS Code settings do you recommend?

"python.linting.enabled": true, "python.linting.flake8Enabled": true, "python.formatting.provider": "black", "editor.formatOnSave": true. Plus the Odoo Snippets extension.

For full developer-team enablement including code review playbooks and CI/CD templates, ECOSIRE Odoo customization provides team-level engagements. Or read how to package an Odoo module for distribution.