Local Odoo Development Setup on Windows

This article provides a step-by-step guide to setting up a Local Odoo development environment on Windows. Because Zodoo relies on Docker, bash, rsync, and Unix-style symlinks, the recommended (and supported) way to run it on Windows is inside WSL2 (Windows Subsystem for Linux). Native PowerShell / CMD setups are not supported. Follow these instructions to ensure a smooth development experience.

Prerequisites

• Windows 10 (build 19041+) or Windows 11.

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

• WSL2 with Ubuntu installed — provides the Linux environment Zodoo needs.

• Docker Desktop for Windows with WSL2 integration enabled — runs the Odoo and Postgres containers. Refer to the Docker Desktop installation guide.

• Windows Terminal (recommended) — gives you a clean tabbed terminal that integrates with WSL.

⚠️ Important — work from inside WSL, not from C:\

Keep your project repositories under your WSL home directory (e.g. ~/projects), not under /mnt/c/.... Cross-filesystem access through /mnt/c is dramatically slower and breaks Zodoo's file-watching and rsync flows.

1. Install WSL2 and Ubuntu

Open PowerShell as Administrator and run:

wsl --install -d Ubuntu
# Installs WSL2 with the Ubuntu distribution as the default Linux environment.
# After install you'll be asked to reboot, then to create a Linux username and password.

Verify WSL2 is the active version:

wsl --set-default-version 2
# Ensures any future distribution uses WSL2 (not the legacy WSL1), which is required by Docker Desktop.

wsl -l -v
# Lists installed distributions and their WSL version. Ubuntu should show VERSION 2.

From this point on, every command in this guide is executed inside the Ubuntu (WSL) terminal, not in PowerShell.

2. Install Docker Desktop & enable WSL Integration

1. Install Docker Desktop for Windows.

2. Open Docker Desktop → Settings → General → tick "Use the WSL 2 based engine".

3. Go to Settings → Resources → WSL Integration → enable integration with your Ubuntu distro.

4. Apply & restart Docker Desktop.

Verify Docker works from inside WSL:

docker version
# Should show both Client and Server versions without errors.
# If you see "Cannot connect to the Docker daemon", re-check the WSL Integration toggle.

3. Install System Dependencies inside WSL

Open the Ubuntu terminal and install the tools Zodoo needs:

sudo apt update && sudo apt upgrade -y
# Refreshes the apt index and upgrades existing packages.

sudo apt install -y git curl rsync pipx build-essential
# git    -> to clone the Odoo repository
# curl   -> used by the Zodoo installer
# rsync  -> required by Zodoo to sync source folders into the Odoo container
# pipx   -> isolates the Zodoo (wodoo) Python CLI
# build-essential -> compilers needed by some Python wheels

pipx ensurepath
# Adds ~/.local/bin to your PATH so the `odoo` command is found after install.
# Close and reopen the terminal afterwards.

(Optional but recommended) Install pyenv to manage Python versions, since newer Odoo releases require Python ≥ 3.10:

curl https://pyenv.run | bash
# Installs pyenv. Follow the on-screen instructions to add pyenv to your shell rc file.

pyenv install 3.12.13
# Installs a modern Python that you can later point Zodoo to.

4. Clone the Odoo Repository

Inside WSL (under your Linux home, e.g. ~/projects):

mkdir -p ~/projects && cd ~/projects
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.

💡 Tip — line endings If the repo contains Windows-style CRLF line endings, configure git inside WSL to keep LF:

git config --global core.autocrlf input
# Stores files with LF in the index but converts to your OS line ending on checkout.

5. 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 inside WSL.
# By default it uses the system Python provided by Ubuntu.

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.

6. Configure Odoo Development Settings

Navigate to the cloned Odoo repository in your IDE (VS Code's WSL: Ubuntu remote is highly recommended) and open a WSL 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`.

Prerequisite: the module you're working on must be listed under install in your project's MANIFEST file — otherwise odoo update will skip it and your changes won't show up in the database.

💡 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 (Ctrl + Shift + R) to bypass Odoo's asset cache.

Problems that might occur

Leftover Wodoo installation

If you encounter issues due to a previous installation of Wodoo (e.g. 📦 Installing /home/user/.odoo/images/wodoo/src via pipx... Unable to parse package spec: /home/user/.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.

rsync errors

If you receive an error related to syncing folders (e.g. AttributeError: 'NoneType' object has no attribute 'groups' originating from rsync_progress_param), make sure rsync is installed inside WSL:

sudo apt install -y rsync
# Installs rsync in your Ubuntu/WSL environment. Zodoo uses it to sync source
# folders into the Odoo container; without it the build/reload step fails.

Cannot connect to the Docker daemon

Open Docker Desktop → Settings → Resources → WSL Integration and confirm that integration with your Ubuntu distro is enabled, then restart Docker Desktop. The docker CLI inside WSL talks to Docker Desktop on Windows over this bridge.

Setting the Python version

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.

Files not updating / changes ignored

Make sure your project lives under ~/... (the WSL filesystem) and not /mnt/c/.... Projects on the Windows drive suffer from broken file-watching and very slow I/O.

Line ending issues (CRLF)

If Odoo or Python complains about syntax errors right after cloning, your repo may have CRLF line endings. Convert with:

sudo apt install -y dos2unix
find . -type f \( -name "*.py" -o -name "*.xml" -o -name "*.csv" \) -exec dos2unix {} \;
# Converts all relevant text files to LF line endings, the format Odoo expects.

Conclusion

By following these steps, you should have a fully functioning Local Odoo development setup on Windows via WSL2. Remember the typical workflow after any change (always run from your WSL terminal):

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.

FAQs