[Skip to content](#main)

[→](/)

[![Avunu](/brand/avunu-logo.svg)![Avunu](/brand/avunu-logo-light.svg)](/)[Services](/services/)[Consulting](/services/consulting/)[ERP](/services/erp/)[Odoo](/services/erp/odoo/)[ERPNext](/services/erp/erpnext/)[Custom software](/services/custom-software/)[Devices & IoT](/services/devices-iot/)[Websites](/services/websites/)[Infrastructure](/services/infrastructure/)[Partners](/partners/)

[Work](/work/)[Open source](/open-source/)[Knowledge base](/kb/)[About](/about/)

[About Avunu](/about/)[Team](/about/team/)[Insights](/insights/)[Contact](/contact/)

[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

- [Services](/services/)[Consulting](/services/consulting/)
- [ERP](/services/erp/)
- [Odoo](/services/erp/odoo/)
- [ERPNext](/services/erp/erpnext/)
- [Custom software](/services/custom-software/)
- [Devices & IoT](/services/devices-iot/)
- [Websites](/services/websites/)
- [Infrastructure](/services/infrastructure/)
- [Partners](/partners/)

[Work](/work/)[Open source](/open-source/)[Knowledge base](/kb/)[About](/about/)

- [About Avunu](/about/)
- [Team](/about/team/)
- [Insights](/insights/)
- [Contact](/contact/)

[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

[Knowledge base](/kb/)[NixOS](/kb/nixos/)Set up an Odoo and OCA development environment with odoo-nix

Search the knowledge basePress/

ESC

Jump to

[Browse the knowledge base](/kb/)[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[NixOS](/kb/nixos/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

↵select↑↓navigateescclose

Search the knowledge base

[Skip to the article](#kb-article)[NixOS](/kb/nixos/)13 articles

- [Overview](/kb/nixos/)
- [A NixOS micro desktop for family and friends](/kb/nixos/nixos-micro-desktop-for-family-and-friends/)
- [Add OCA modules to an odoo-nix project](/kb/nixos/adding-oca-modules-with-odoo-nix/)
- [Build a Firefox web kiosk USB drive with web_kiosk](/kb/nixos/building-a-web-kiosk-usb-with-web-kiosk/)
- [Build production images with frappe-nix](/kb/nixos/building-production-images-with-frappe-nix/)
- [Mount and sync cloud storage on NixOS with nixos-rclone](/kb/nixos/mounting-cloud-storage-with-nixos-rclone/)
- [Reference architecture for self-hosting business systems on NixOS](/kb/nixos/reference-architecture-for-self-hosting-business-systems/)
- [Run Frappe as a NixOS service](/kb/nixos/running-frappe-as-a-nixos-service/)
- [Run Odoo as a NixOS service](/kb/nixos/running-odoo-as-a-nixos-service/)
- [Run WordPress on FrankenPHP with wordpress-nix](/kb/nixos/wordpress-on-frankenphp-with-wordpress-nix/)
- [Set up a reproducible Frappe development environment with frappe-nix](/kb/nixos/frappe-dev-environment-with-frappe-nix/)
- [Set up an Odoo and OCA development environment with odoo-nix](/kb/nixos/odoo-dev-environment-with-odoo-nix/)
- [Why Nix for business systems](/kb/nixos/why-nix-for-business-systems/)
- [WordPress performance and hardening on Nix](/kb/nixos/wordpress-performance-and-hardening-on-nix/)

Other sections[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

In NixOS: 13 articles

[Overview](/kb/nixos/)[A NixOS micro desktop for family and friends](/kb/nixos/nixos-micro-desktop-for-family-and-friends/)[Add OCA modules to an odoo-nix project](/kb/nixos/adding-oca-modules-with-odoo-nix/)[Build a Firefox web kiosk USB drive with web_kiosk](/kb/nixos/building-a-web-kiosk-usb-with-web-kiosk/)[Build production images with frappe-nix](/kb/nixos/building-production-images-with-frappe-nix/)[Mount and sync cloud storage on NixOS with nixos-rclone](/kb/nixos/mounting-cloud-storage-with-nixos-rclone/)[Reference architecture for self-hosting business systems on NixOS](/kb/nixos/reference-architecture-for-self-hosting-business-systems/)[Run Frappe as a NixOS service](/kb/nixos/running-frappe-as-a-nixos-service/)[Run Odoo as a NixOS service](/kb/nixos/running-odoo-as-a-nixos-service/)[Run WordPress on FrankenPHP with wordpress-nix](/kb/nixos/wordpress-on-frankenphp-with-wordpress-nix/)[Set up a reproducible Frappe development environment with frappe-nix](/kb/nixos/frappe-dev-environment-with-frappe-nix/)[Set up an Odoo and OCA development environment with odoo-nix](/kb/nixos/odoo-dev-environment-with-odoo-nix/)[Why Nix for business systems](/kb/nixos/why-nix-for-business-systems/)[WordPress performance and hardening on Nix](/kb/nixos/wordpress-performance-and-hardening-on-nix/)

Other sections[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

NixOSSet up an Odoo and OCA development environment with odoo-nix

Scaffold an Odoo project with odoo-nix, start the devenv shell, and run the daily odoo CLI commands for databases, modules and upgrades.

UpdatedOct 5, 2026

Applies toodoo-nixOdoo 18.0Odoo 19.0devenvNix flakes

Tagsnixosodoodevenvoca

Reading time10 min

On this page[What you get](#what-you-get)[Requirements](#requirements)[Scaffold a project](#scaffold-a-project)[What the scaffolder creates](#what-the-scaffolder-creates)[Enter the shell and start the stack](#enter-the-shell-and-start-the-stack)[Ports](#ports)[Create the database](#create-the-database)[Daily commands](#daily-commands)[Upgrade modules after a code change](#upgrade-modules-after-a-code-change)[Open a shell](#open-a-shell)[Add OCA modules](#add-oca-modules)[Update the workspace](#update-the-workspace)[The generated configuration](#the-generated-configuration)[addons_path](#addons_path)[odoo.conf](#odooconf)[Mail in development](#mail-in-development)[Live reload](#live-reload)[Running other Odoo commands](#running-other-odoo-commands)[Troubleshooting](#troubleshooting)[Related](#related)

This document covers creating an Odoo project with [odoo-nix](https://github.com/Avunu/odoo-nix), entering its development shell, and the commands you use every day. Use it when you want a reproducible Odoo Community (OCB) plus [OCA](https://github.com/OCA) setup that a new machine can reproduce with one checkout and one command.

## What you get

odoo-nix keeps the project itself small. You own a thin `flake.nix`, a `pyproject.toml`, a `modules.txt` list of modules to install, and your own addons. odoo-nix supplies the rest:

A development shell (via devenv) running PostgreSQL, Odoo and Mailpit.

A Python environment built from your `pyproject.toml` and `uv.lock`.

An `odoo.conf` generated from Nix options, with `addons_path` derived from the folders on disk.

One `odoo` command for databases, modules and workspace updates.

## Requirements

Nix with flakes enabled.

[direnv](https://direnv.net) for automatic shell entry. Without it, use `nix develop --no-pure-eval` instead.

git, since OCB and every OCA repository are added as git submodules.

## Scaffold a project

Run the scaffolder from anywhere. It is an interactive [gum](https://github.com/charmbracelet/gum) prompt that asks for the Odoo series, then whether to add curated OCA bundles and individual OCA modules (both optional), then a project directory. It does not ask for a database name. The default is `odoo`, and `--db` changes it.

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">run</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">github:Avunu/odoo-nix</span>
```

For a scripted run, pass everything as flags. `--series` is required when there is no terminal. The last argument is the target directory, which must be empty or not exist.

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">run</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">github:Avunu/odoo-nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--series</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">18.0</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--bundles</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">base</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--modules</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">account_financial_report,repair_order_group</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--name</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">myproject</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--db</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">myproject</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">myproject</span>
```

| Flag        | Meaning                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------ |
| `--series`  | Odoo series, `18.0` or `19.0`. It fixes the Python version (3.11 for 18.0, 3.12 for 19.0). |
| `--bundles` | Comma-separated curated OCA bundles to install.                                            |
| `--modules` | Comma-separated OCA module names to install. `--apps` is an alias.                         |
| `--name`    | Project name. Defaults to the target directory name.                                       |
| `--db`      | Default database name. Defaults to `odoo`.                                                 |

OCA software is opt-in. If you decline both prompts, or pass neither `--bundles` nor `--modules`, you get plain Odoo core. If you pass both, the two selections are combined and de-duplicated.

When you pick a module, the scaffolder works out which OCA repositories it depends on, transitively, and adds only those as submodules. It then writes the wrapper flake, generates `pyproject.toml` and runs `uv lock`.

Note

18.0 is the default for the `odooSeries` option and has the richest OCA catalog. 19.0 is supported, but fewer OCA modules have been ported to it, so the picker offers fewer choices.

### What the scaffolder creates

```text
.
├── flake.nix          # thin wrapper around odoo-nix
├── pyproject.toml     # Odoo core deps plus the modules you chose, locked in uv.lock
├── uv.lock
├── modules.txt        # the OCA install set, one module per line
├── odoo/              # OCB source (git submodule, branch = series)
├── modules/           # OCA repositories (git submodules, one per repo)
├── custom/            # your own modules
└── odoo.conf          # symlink into the Nix store (generated on first shell entry)
```

`.devenv/state/` holds the development PostgreSQL cluster and Odoo's filestore. Nothing mutable is tracked by git. The generated `.gitignore` also excludes the `odoo.conf`, `.venv` and `odools.toml` symlinks.

## Enter the shell and start the stack

From the project directory:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">direnv</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">allow</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">devenv</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">up</span>
```

The scaffolded `.envrc` contains `use flake . --no-pure-eval`, so `direnv allow` builds the environment and loads it into your shell. `devenv up` then runs three processes:

`postgres`, with its data under `.devenv/state`.

`odoo`, running `odoo-bin -c odoo.conf --dev=all` as a single threaded process that serves HTTP and websockets.

`mailpit`, an SMTP sink with a web interface. `odoo` starts after `postgres` (and after `mailpit` while the mail catcher is enabled).

Leave `devenv up` running and open a second shell in the same directory for the commands below.

On shell entry, odoo-nix also checks out submodules that a fresh clone has never had, symlinks the generated `odoo.conf` into place, creates the filestore and `custom/` directories, and prints a banner listing the main commands. That means a fresh `git clone --recurse-submodules` followed by `direnv allow` is a complete setup.

### Ports

| Service               | Address                 |
| --------------------- | ----------------------- |
| Odoo                  | `http://localhost:8069` |
| Mailpit web interface | `http://localhost:8025` |
| Mailpit SMTP          | 127.0.0.1:1025          |

These are the defaults. You can change them through `odooConf.httpPort` and the `mailcatch.*` options in `flake.nix`.

## Create the database

In the second shell:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">odoo</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">db</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">provision</span>
```

With no argument, `provision` uses `db_name` from the generated `odoo.conf`, which is the name you gave the scaffolder with `--db`. You can also pass a name, or set `ODOO_DB`.

The command is idempotent:

If the database does not exist, or exists without an Odoo schema, it installs `base` plus every module in `modules.txt`.

If the database is already initialized, it migrates it instead of reinstalling, after taking a `zip` snapshot first. Add `--no-backup` to skip that snapshot.

Then open `http://localhost:8069`.

## Daily commands

Everything below is a subcommand of the single `odoo` command, available inside the dev shell.

| Task                                                         | Command                                 |
| ------------------------------------------------------------ | --------------------------------------- |
| Create the database and install `modules.txt`, or migrate it | `odoo db provision [DB]`                |
| Upgrade specific modules                                     | `odoo db upgrade MODULE[,MODULE2] [DB]` |
| Upgrade whatever changed since the last migration            | `odoo db migrate [DB]`                  |
| Open an Odoo Python shell                                    | `odoo shell [DB]`                       |
| Add OCA modules                                              | `odoo module add [MODULE ...]`          |
| Add a curated OCA bundle                                     | `odoo module add-bundle [NAME ...]`     |
| Pull submodules, refresh dependencies, re-lock, migrate      | `odoo project update`                   |
| Run a module's tests                                         | `odoo test MODULE[,MODULE2] [DB]`       |
| List databases                                               | `odoo db list`                          |

Note

Earlier versions of odoo-nix shipped separate hyphenated scripts such as `odoo-shell`, `odoo-add-module`, `odoo-update` and `odoo-test`. The `odoo` subcommands above replace them (`odoo shell`, `odoo module add`, `odoo project update`, `odoo test`). If an older guide uses the hyphenated names, use the subcommands instead.

### Upgrade modules after a code change

`odoo db upgrade` runs Odoo's `-u` for the modules you name and shows a live progress bar, followed by a per-module summary table:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">odoo</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">db</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">upgrade</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">my_module,other_module</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">odoo</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">db</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">upgrade</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">my_module</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--all</span>
```

`--all` here means every database matching `dbfilter`, not every module. To upgrade every module whose code or version changed, without naming them, use `odoo db migrate`. It compares a checksum of each module against the one stored at the last successful migration and prints a plan before it touches anything. Useful flags:

`--full` updates every installed module (`-u all`).

`--also m1,m2` forces extra modules into the update.

`--snapshot zip|dump|none` controls the pre-migration snapshot (default `zip`).

`--rollback` restores the snapshot if the update fails.

### Open a shell

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">odoo</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">shell</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">odoo</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">shell</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">myproject</span>
```

This starts Odoo's own `shell` command against the database, using the generated `odoo.conf`.

### Add OCA modules

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">odoo</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">module</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">add</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">odoo</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">module</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">add</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">account_financial_report</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">odoo</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">module</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">add-bundle</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">base</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">sales</span>
```

With no arguments in a terminal, `odoo module add` asks whether to browse the OCA catalog or add from a Git URL. Either way, it adds any missing repositories as submodules, records the modules in `modules.txt`, regenerates the managed blocks in `pyproject.toml` and re-locks. When it finishes, reload the environment and install:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">direnv</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">reload</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">odoo</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">db</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">provision</span>
```

`direnv reload` is required. It makes Nix re-derive `addons_path` and rebuild the Python environment.

You are not limited to OCA. Give `odoo module add` any Git URL, or `owner/repo` for GitHub, with an optional branch and submodule folder name:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">odoo</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">module</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">add</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">https://git.example.com/owner/repo.git</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">odoo</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">module</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">add</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">owner/repo</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">18.0</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">my-repo</span>
```

The branch defaults to your Odoo series. If the repository has no such branch, it offers the repository's default branch. A repository with several modules asks which ones to record in `modules.txt`.

`add-bundle` takes names from the bundled `oca-bundles.json` in odoo-nix, such as `base` and `sales`. Any member that has no module for your series is reported and dropped rather than left to fail at provision time.

### Update the workspace

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">odoo</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">project</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">update</span>
```

This pulls the submodules on their pinned branches, re-aggregates the OCA Python dependencies and runs `uv lock`. It then migrates every database matching `dbfilter`. Pass `--no-migrate` to skip the migration step.

Warning

`odoo project update` moves submodule pointers. Review `git status`, test, and commit the new pointers deliberately. Shell entry never advances submodules for you.

## The generated configuration

### addons_path

odoo-nix builds `addons_path` on every evaluation from the directories that are actually present, in this order:

`./odoo/odoo/addons`, then `./odoo/addons` (OCB core).

One entry per repository under `modules/` that contains at least one module (an immediate child with `__manifest__.py`), sorted by name.

`./custom`.

Any extra entries from `layout.extraAddons`.

Add or remove a submodule and the path changes with it. There is no list to keep in sync. Order matters because Odoo uses the first match.

### odoo.conf

The `odoo.conf` at the project root is a symlink to a read-only file in the Nix store. It is generated from the `odooConf.*` options in your `flake.nix`, plus the derived `addons_path`. Never edit it. Change the options and reload instead:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">odoo-nix</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FFA198;--shiki-dark-font-style:italic;--shiki-light:#82071E;--shiki-light-font-style:italic">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">enable</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">true</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">projectName</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"myproject"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">workspaceRoot</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">./.</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">odooSeries</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"18.0"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">python</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">pkgs</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">.</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">python311</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">  </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">odooConf</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">dbName</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"myproject"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">;</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}</span><span style="--shiki-dark:#FFA198;--shiki-dark-font-style:italic;--shiki-light:#82071E;--shiki-light-font-style:italic">;</span>
```

Other options you may want include `odooConf.httpPort`, `odooConf.workers`, `odooConf.withoutDemo` and `odooConf.extra` for arbitrary extra keys. Keep `workers` at its default of `0` in development, because live code reload only works on the threaded server.

## Mail in development

With `mailcatch.enable` on (the default), every outgoing email from Odoo is redirected to Mailpit, so nothing can reach a real recipient from your machine. Open `http://localhost:8025` to read what Odoo sent.

This works through a small server-wide addon that odoo-nix ships and loads from the Nix store. It is not installed into any database and does not appear in `custom/` or `modules.txt`. It applies to the web server, `odoo shell` and `--stop-after-init` runs alike. The catch-all exists only in the dev shell. Production deployments do not load it.

## Live reload

The dev server runs with `--dev=all`. Edits to `.py` files on the `addons_path` restart the server in place. XML views, QWeb templates and assets need only a browser refresh. Odoo's framework code under `odoo/odoo/` is not watched, so restart `devenv up` after changing it.

At startup, look for this line to confirm the watcher is active:

```text
AutoReload watcher running with watchdog
```

If a module's change adds a field or changes data files, a restart is not enough. Run `odoo db upgrade` for that module.

## Running other Odoo commands

`db`, `module`, `project`, `shell` and `test` are odoo-nix's own subcommands. Anything else passes straight through to the real `odoo-bin`, so `odoo scaffold`, `odoo populate` and the rest of Odoo's command set still work. With no subcommand, `odoo` starts the server. The options `-c/--config`, `-d/--database` and `--db-host/--db-port/--db-user/--db-password` are accepted before the subcommand name.

## Troubleshooting

**A module you just added is not found.** Run `direnv reload` so `addons_path` is re-derived and the Python environment is rebuilt, then run `odoo db provision`.

**Changed code but the schema did not follow.** Odoo only creates columns and reloads data for modules being updated. Run `odoo db upgrade <MODULE>` or `odoo db migrate`.

**`uv lock` fails during `module add` or scaffolding.** The scaffolder reports this as usually a dependency version conflict. Adjust `[project].dependencies` in `pyproject.toml` and run `uv lock` again. Do not hand-edit the blocks between the `>>> odoo-nix` and `<<< odoo-nix` markers.

**`odoo test` refuses to run.** It checks that browser tours can actually run, since Odoo reports a skipped tour like a pass. It needs the `websocket-client` package and a headless browser on `PATH`. The scaffolded `pyproject.toml` already lists `websocket-client` in the dev group, so the browser is usually what is missing.

## Related

[Adding OCA Modules with odoo-nix](/kb/nixos/adding-oca-modules-with-odoo-nix/), for how the module picker, bundles and submodules work.

[Running Odoo as a NixOS Service](/kb/nixos/running-odoo-as-a-nixos-service/), for deploying the project with the production NixOS module.

[Why Nix for Business Systems](/kb/nixos/why-nix-for-business-systems/), for when this approach is and is not a good fit.

[odoo-nix on GitHub](https://github.com/Avunu/odoo-nix) for the full option reference, production NixOS module and container image.

Sources

- [github.com/Avunu/odoo-nix](https://github.com/Avunu/odoo-nix)
- [github.com/OCA/OCB](https://github.com/OCA/OCB)
- [github.com/OCA](https://github.com/OCA)
- [devenv.sh](https://devenv.sh)
- [direnv.net](https://direnv.net)
- [github.com/axllent/mailpit](https://github.com/axllent/mailpit)

Need help with NixOS?

Our notes can take you a long way, but sometimes you'd rather have someone who's done it before.

[Managed infrastructure](/services/infrastructure/)

[← PreviousSet up a reproducible Frappe development environment with frappe-nix](/kb/nixos/frappe-dev-environment-with-frappe-nix/)[Next →Why Nix for business systems](/kb/nixos/why-nix-for-business-systems/)

CC0This article is in the public domain ([CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/)), code samples included. Use it however helps you.

On this page

- [What you get](#what-you-get)
- [Requirements](#requirements)
- [Scaffold a project](#scaffold-a-project)
- [What the scaffolder creates](#what-the-scaffolder-creates)
- [Enter the shell and start the stack](#enter-the-shell-and-start-the-stack)
- [Ports](#ports)
- [Create the database](#create-the-database)
- [Daily commands](#daily-commands)
- [Upgrade modules after a code change](#upgrade-modules-after-a-code-change)
- [Open a shell](#open-a-shell)
- [Add OCA modules](#add-oca-modules)
- [Update the workspace](#update-the-workspace)
- [The generated configuration](#the-generated-configuration)
- [addons_path](#addons_path)
- [odoo.conf](#odooconf)
- [Mail in development](#mail-in-development)
- [Live reload](#live-reload)
- [Running other Odoo commands](#running-other-odoo-commands)
- [Troubleshooting](#troubleshooting)
- [Related](#related)

[Back to top↑](#top)

Services

- [ERP implementation](/services/erp/)
- [Odoo](/services/erp/odoo/)
- [ERPNext](/services/erp/erpnext/)
- [Custom software](/services/custom-software/)
- [Devices & IoT](/services/devices-iot/)
- [Websites](/services/websites/)
- [Infrastructure](/services/infrastructure/)

Resources

- [Our work](/work/)
- [Open source](/open-source/)
- [Knowledge base](/kb/)
- [Insights](/insights/)

Company

- [About](/about/)
- [Team](/about/team/)
- [Partners](/partners/)
- [Contact](/contact/)

Clients

- [Project portal](https://erp.avunu.net/projects)
- [Invoices](https://erp.avunu.net/)
- [Support](https://erp.avunu.net/)

[![Avunu](/brand/avunu-logo-light.svg)](/)[\<av-icon data-jx-static>\<svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" stroke="none" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">\<path d="M20.400 20.500h-3.600v-5.600c0-1.300 0-3-1.800-3s-2.100 1.400-2.100 2.900v5.700H9.400V9h3.400v1.600c.5-.9 1.600-1.900 3.400-1.900 3.600 0 4.300 2.400 4.300 5.500v6.300zM5.300 7.400a2.100 2.100 0 1 1 0-4.100 2.100 2.100 0 0 1 0 4.100zm1.800 13.100H3.600V9h3.500v11.500zM22.200 0H1.800C.8 0 0 .8 0 1.700v20.600c0 .9.800 1.700 1.800 1.700h20.400c1 0 1.800-.8 1.800-1.700V1.700C24 .8 23.200 0 22.200 0z">\</path>\</svg>\</av-icon>](https://www.linkedin.com/company/avunu)[\<av-icon data-jx-static>\<svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" stroke="none" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">\<path d="M12 .3a12 12 0 0 0-3.8 23.4c.6.1.8-.3.8-.6v-2c-3.3.7-4-1.6-4-1.6-.6-1.4-1.4-1.8-1.4-1.8-1-.7.1-.7.1-.7 1.2.1 1.8 1.2 1.8 1.2 1 1.8 2.8 1.3 3.5 1 .1-.8.4-1.3.7-1.6-2.7-.3-5.5-1.3-5.5-5.9 0-1.3.5-2.4 1.2-3.2-.1-.3-.5-1.5.1-3.2 0 0 1-.3 3.3 1.2a11.500 11.500 0 0 1 6 0c2.300-1.500 3.300-1.200 3.300-1.200.6 1.700.2 2.900.1 3.200.8.8 1.200 1.900 1.200 3.200 0 4.600-2.800 5.600-5.500 5.900.4.400.8 1.100.8 2.200v3.300c0 .3.2.7.8.6A12 12 0 0 0 12 .3">\</path>\</svg>\</av-icon>](https://github.com/Avunu)[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

Avunu LLC · 948 East Philadelphia Street, York, PA 17403 · (717) 814-8540Knowledge base articles are in the public domain[Privacy](/privacy/)[Terms](/terms/)
