[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/)[Odoo](/kb/odoo/)Set up and work in an Odoo 18 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)[Odoo](/kb/odoo/)7 articles

- [Overview](/kb/odoo/)
- [A repair shop workflow on Odoo 18, from inspection to invoice](/kb/odoo/repair-shop-workflow-on-odoo/)
- [Importing documents from email into Odoo](/kb/odoo/importing-documents-from-email-into-odoo/)
- [Migrating from QuickBooks to Odoo with a clean cutover](/kb/odoo/migrating-from-quickbooks-to-odoo/)
- [Odoo Community and OCA overview](/kb/odoo/odoo-community-and-oca-overview/)
- [Set up and work in an Odoo 18 development environment with odoo-nix](/kb/odoo/odoo-development-environment/)
- [Set up two-way SMS in Odoo with Twilio](/kb/odoo/two-way-sms-in-odoo-with-twilio/)
- [Test custom Odoo modules from the command line](/kb/odoo/testing-custom-odoo-modules/)

Other sections[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[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/)

In Odoo: 7 articles

[Overview](/kb/odoo/)[A repair shop workflow on Odoo 18, from inspection to invoice](/kb/odoo/repair-shop-workflow-on-odoo/)[Importing documents from email into Odoo](/kb/odoo/importing-documents-from-email-into-odoo/)[Migrating from QuickBooks to Odoo with a clean cutover](/kb/odoo/migrating-from-quickbooks-to-odoo/)[Odoo Community and OCA overview](/kb/odoo/odoo-community-and-oca-overview/)[Set up and work in an Odoo 18 development environment with odoo-nix](/kb/odoo/odoo-development-environment/)[Set up two-way SMS in Odoo with Twilio](/kb/odoo/two-way-sms-in-odoo-with-twilio/)[Test custom Odoo modules from the command line](/kb/odoo/testing-custom-odoo-modules/)

Other sections[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[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/)

OdooSet up and work in an Odoo 18 development environment with odoo-nix

Repository layout, daily commands, adding OCA modules, running a dev server with a mail catcher, and upgrading modules in an odoo-nix managed Odoo 18 project.

UpdatedNov 7, 2026

Applies toOdoo 18.0 (OCB)OCA 18.0 modulesodoo-nixdevenvPostgreSQL 16

Tagsodoodevenvnixdevelopment

Reading time11 min

On this page[What you get](#what-you-get)[Repository layout](#repository-layout)[modules.txt](#modulestxt)[pyproject.toml](#pyprojecttoml)[odoo.conf](#odooconf)[Start working](#start-working)[Run the dev server](#run-the-dev-server)[Mail never leaves your machine](#mail-never-leaves-your-machine)[Live reload](#live-reload)[Daily commands](#daily-commands)[Add OCA modules](#add-oca-modules)[Apply code changes to a database](#apply-code-changes-to-a-database)[Upgrade specific modules](#upgrade-specific-modules)[Upgrade whatever changed](#upgrade-whatever-changed)[Run tests](#run-tests)[Everything else](#everything-else)[Editor setup](#editor-setup)[Start a new project](#start-a-new-project)[Troubleshooting](#troubleshooting)

This guide is for a developer joining an Odoo 18 Community project that uses OCA modules and is managed with [odoo-nix](https://github.com/Avunu/odoo-nix). It covers how the repository is laid out, which commands you run every day, how to add OCA modules, how to run the dev server, and how to apply code changes to a database.

Production hosting is a separate topic and is not covered here. For how the module set is chosen, read [Odoo Community and OCA Overview](/kb/odoo/odoo-community-and-oca-overview/) first.

## What you get

odoo-nix turns the project into one reproducible shell. You need Nix with flakes enabled and [direnv](https://direnv.net/). Everything else comes from the flake:

PostgreSQL 16, started for you by devenv.

The Odoo server, running from source with `--dev=all`.

Mailpit, a local mail catcher.

A pinned Python environment (Python 3.11 for Odoo 18) built from `pyproject.toml` and `uv.lock`.

One `odoo` command for database, module and project tasks. Anything it does not know is passed straight to the real `odoo-bin`.

## Repository layout

| Path                        | What it is                                                              |
| --------------------------- | ----------------------------------------------------------------------- |
| `odoo/`                     | The OCB 18.0 source, a git submodule.                                   |
| `modules/`                  | OCA repositories, one git submodule per repository.                     |
| `custom/`                   | The project's own modules.                                              |
| `modules.txt`               | The install set: one module name per line.                              |
| `pyproject.toml`, `uv.lock` | The Python environment, resolved by uv.                                 |
| `flake.nix`                 | A thin wrapper that sets project name, series, database name and so on. |
| `odoo.conf`                 | A symlink into the Nix store. Generated, never edited.                  |
| `.venv`, `odools.toml`      | Symlinks for editors. Generated.                                        |
| `.devenv/state/`            | The development PostgreSQL cluster and the Odoo filestore. Not tracked. |

Three of these deserve a closer look.

### modules.txt

`odoo db provision` installs `base` plus every module listed in `modules.txt`. The file is also what the Python environment is built from: each listed module becomes an install root in `pyproject.toml`, and uv resolves the dependency graph from there. A module listed here must exist on disk, either under `modules/` or under `custom/`.

`odoo module add` keeps the file sorted and free of duplicates. Many projects keep it to OCA modules only and install their own modules from `custom/` explicitly, but nothing in odoo-nix forces that convention. Follow whatever your project already does.

### pyproject.toml

Three blocks in `pyproject.toml` are managed by odoo-nix and sit between marker comments that start with `# >>> odoo-nix:`: the install set, the module sources, and the build dependencies for packages that only ship as source. Do not edit anything between the markers. odoo-nix regenerates them whenever you run `odoo module add`, `odoo module add-bundle` or `odoo project update`.

The `[dependency-groups].dev` block is yours. It already carries `watchdog` (for code reload), `freezegun` and `websocket-client` (both needed to run Odoo tests). Leave those in. Without `freezegun` no Odoo test can run at all.

### odoo.conf

The file is rendered from your flake settings and the folders on disk. `addons_path` is derived from what exists, in this order: the two core OCB roots, each OCA repository under `modules/` that contains a module, then `custom/`. You never maintain that list by hand.

To change a setting such as the database name or the HTTP port, change the `odooConf` options in `flake.nix`, run `direnv reload`, and restart `devenv up`.

## Start working

On a fresh clone, take the submodules along and let direnv build the shell:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">git</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">clone</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--recurse-submodules</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">REPO_UR</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">L</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">PROJECT_DI</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">R</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span>
<span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">cd</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">PROJECT_DI</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">R</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span>
<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>
```

If you do not use direnv, `nix develop --no-pure-eval` gives you the same shell. The first entry also checks out any submodule you have never had, so a clone made without `--recurse-submodules` still works.

### Run the dev server

Start PostgreSQL, Odoo and Mailpit together:

```
<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>
```

In a second terminal, in the same project directory, create the database and install the install set:

```
<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, the command uses the database name configured in `odoo.conf`. It is safe to run again: on a database that already exists it migrates instead of reinstalling.

When it finishes, open Odoo at `http://localhost:8069` and the mail catcher at `http://localhost:8025`.

### Mail never leaves your machine

In the dev shell every outgoing email is redirected to Mailpit. This is done by a small server-wide addon that ships with odoo-nix, so it covers every database on the server and cannot be bypassed by an outgoing mail server record. It is never installed into a database and never copied into your repository. At startup the Odoo log warns that all outgoing email is being redirected.

Use Mailpit to check invitations, quotation emails and notifications. The catch-all exists only in the dev shell. It is not part of the server or container builds.

### Live reload

Edits are picked up without restarting `devenv up`:

A change to a `.py` file anywhere on the `addons_path` restarts the server in place. A syntax error is logged and the restart is skipped until you fix it.

XML views, QWeb templates and JS or SCSS assets are re-read from disk. Reload the browser.

Odoo framework code under `odoo/odoo/` is not watched. Restart `devenv up` after changing it.

Look for `AutoReload watcher running with watchdog` in the log to confirm the watcher is on. Reload only works with `workers = 0`, which is the dev default.

Note

Reload picks up code, not schema. A new field, a changed data file or a migration script only takes effect once the module is upgraded. See [Apply code changes to a database](#apply-code-changes-to-a-database).

## Daily commands

Run these from the project directory inside the dev shell.

| Command                                  | What it does                                                                  |
| ---------------------------------------- | ----------------------------------------------------------------------------- |
| `devenv up`                              | Starts PostgreSQL, Odoo and Mailpit.                                          |
| `odoo db provision [DB]`                 | Creates the database and installs `modules.txt`, or migrates it if it exists. |
| `odoo db upgrade <MODULE[,MODULE]> [DB]` | Upgrades the named modules, with a progress bar and a summary table.          |
| `odoo db migrate [DB]`                   | Upgrades only the modules whose code or version changed.                      |
| `odoo shell [DB]`                        | Opens the Odoo Python shell.                                                  |
| `odoo test <MODULE[,MODULE]> [DB]`       | Runs module tests.                                                            |
| `odoo test --all --fresh-db`             | Tests every addon of the repository in a throwaway database.                  |
| `odoo module add [MODULE ...]`           | Adds OCA modules and their repositories.                                      |
| `odoo project update`                    | Pulls submodules, refreshes dependencies, re-locks, then migrates.            |
| `odoo db backup [DB]`                    | Backs up a database (schema and filestore by default).                        |
| `odoo db list`                           | Lists databases.                                                              |

Commands that take a database fall back to the one in `odoo.conf`. The `db upgrade`, `db migrate` and `db backup` commands also accept `--all` for every database matching `dbfilter`.

## Add OCA modules

`odoo module add` resolves which OCA repositories a module needs, adds only the missing ones as submodules under `modules/`, records the modules in `modules.txt`, regenerates the managed blocks in `pyproject.toml` and re-locks.

```
<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:#8B949E;--shiki-light:#6E7781"># interactive picker</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:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">MODULE_NAM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">             </span><span style="--shiki-dark:#8B949E;--shiki-light:#6E7781"># by name</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:#8B949E;--shiki-light:#6E7781"># pick a curated bundle</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><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">         </span><span style="--shiki-dark:#8B949E;--shiki-light:#6E7781"># bundles by name</span>
```

The picker lists every installable module in the bundled catalog for your series, not just applications. Bundles live in `data/oca-bundles.json` in the odoo-nix repository and include `base`, `oca-accounting`, `project`, `purchase` and `sales`.

You can also add a repository that is not in the OCA catalog, from any git host:

```
<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://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">17.0</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">my-repo</span>
```

The second form is GitHub shorthand with an explicit branch and a submodule folder name. When you leave the branch out, odoo-nix uses your Odoo series and falls back to the repository's default branch if that series does not exist.

After any add, reload the shell so Nix re-derives `addons_path` and rebuilds the Python environment:

```
<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>
```

Then restart `devenv up`. Adding a module does not install it into a database you already have. On an existing database, `odoo db provision` only updates what is installed, so install the new modules from the Apps menu (use Update Apps List first so Odoo notices them). A brand-new database picks up everything in `modules.txt` when you run `odoo db provision`.

Check `git status` and commit the whole result together: `.gitmodules`, the new submodule folders, `modules.txt`, `pyproject.toml` and `uv.lock`.

Tip

Treat a submodule update as a code change. OCA modules vary in maturity, so after `odoo project update` smoke-test the features you depend on before you commit the new submodule pointers.

## Apply code changes to a database

Odoo creates columns, reloads data files and runs migration scripts only for modules being updated. Changed code without an update leaves the schema silently behind the code. You have two tools.

### Upgrade specific modules

When you know which module you changed:

```
<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:#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,my_other_module</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">D</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">B</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span>
```

### Upgrade whatever changed

After pulling a teammate's work, or after `git submodule` pointers move, let odoo-nix work out the set:

```
<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">migrate</span>
```

It compares each module's content checksum with the one stored the last time a migration succeeded, and each module's recorded version with its manifest. It prints the plan before it does anything. Before updating it takes a snapshot of the database (a zip with the filestore, by default). Useful options:

`--full` updates every installed module instead of only the changed ones.

`--also <MODULE,MODULE>` forces specific modules into the update.

`--snapshot zip|dump|none` chooses the snapshot format, or skips it.

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

The first migration on a database with no stored checksums updates every module once to set a baseline. `odoo db provision` records that baseline for a fresh install, so you only meet it on a database restored from elsewhere. The checksums use the same algorithm as the OCA [`module_auto_update`](https://github.com/OCA/server-tools/tree/18.0/module_auto_update) module.

`odoo project update` runs the same migration across every database matching `dbfilter` after it updates the code. Pass `--no-migrate` to skip that step.

## Run tests

This is the short version. [Testing Custom Odoo Modules](/kb/odoo/testing-custom-odoo-modules/) covers tags, phases and writing tests that survive upgrades.

```
<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">test</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:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">TEST_D</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">B</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span>
```

Use a separate database from the one you click around in. The command upgrades the module with `-u`, so the module must already be installed in that database. It refuses to run if the headless browser or the `websocket-client` package is missing, because Odoo would otherwise skip browser tours and report that as a pass. You can override that with `ODOO_NIX_TEST_ALLOW_SKIP=1`.

If the dev server is running, the test run clashes with its ports. Use the `odoo-bin` passthrough with different ports instead:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">odoo</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-d</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">TEST_D</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">B</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">-u</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">--test-enable</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--test-tags</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">--stop-after-init</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--http-port</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">8098</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--gevent-port</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">8097</span>
```

To test the way CI does, install every addon of the repository into a new database that is dropped afterwards:

```
<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">test</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--all</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--fresh-db</span>
```

`--all` leaves out the addons the repository lists as untested in `pyproject.toml`. A repository that uses odoo-nix's [repository standards](https://docs.avunu.net/odoo-nix/docs/standards/) runs its whole CI test gate, with coverage and a scan of the log for warnings, with `odoo-nix gate test`; see [Testing Custom Odoo Modules](/kb/odoo/testing-custom-odoo-modules/#run-tests-with-odoo-nix).

## Everything else

Any command the `odoo` wrapper does not know goes to `odoo-bin` unchanged, so `scaffold`, `populate`, `cloc` and the rest still work. Database housekeeping lives under `odoo db`:

```
<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">duplicate</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">SOURCE_D</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">B</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">NEW_D</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">B</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></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">restore</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">D</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">B</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">BACKUP_FIL</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</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">--force</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">drop</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">D</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">B</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">--yes</span>
```

Backups land in `.devenv/state/odoo/backups/<DB>/` unless you pass `--path`. Take one before experiments.

## Editor setup

The shell links `./.venv` to the Nix-built Python environment and generates `odools.toml` for the Odoo language server. For VS Code it seeds `.vscode/settings.json` and a recommendation for the `Odoo.odoo` extension, once, and never overwrites your own files. Other editors can point their language server at `./.venv` and the `.devenv/state/pythonpath` folder.

## Start a new project

If you are starting from nothing rather than joining a project, the scaffolder creates the layout above, adds OCB and your chosen OCA repositories as submodules, and locks the Python environment:

```
<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:#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:#79C0FF;--shiki-light:#0550AE">--name</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">PROJECT_NAM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</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:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">DB_NAM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">TARGET_DI</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">R</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span>
```

Add `--bundles <NAME>` or `--modules <MODULE,MODULE>` to preselect OCA content. Without them you get plain Odoo core, and you can add modules later with `odoo module add`.

## Troubleshooting

**A module you just added is not found.** Run `direnv reload` so `addons_path` is regenerated, restart `devenv up`, then use Update Apps List in Odoo.

**Python changes do not reload.** Check the log for the `AutoReload watcher` line, and confirm `workers` is 0.

**A new field is missing in the UI or errors in the database.** Upgrade the module with `odoo db upgrade`, or run `odoo db migrate`.

**`uv lock` fails after adding a module.** Fix the cause reported in the output, then run `odoo project update` to regenerate the managed blocks and lock again.

Sources

- [github.com/Avunu/odoo-nix](https://github.com/Avunu/odoo-nix)
- [github.com/OCA/OCB](https://github.com/OCA/OCB)
- [odoo-community.org](https://odoo-community.org/)
- [github.com/OCA/server-tools/tree/18.0/module_auto_update](https://github.com/OCA/server-tools/tree/18.0/module_auto_update)

Need help with Odoo?

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

[Odoo implementation](/services/erp/odoo/)

[← PreviousOdoo Community and OCA overview](/kb/odoo/odoo-community-and-oca-overview/)[Next →Set up two-way SMS in Odoo with Twilio](/kb/odoo/two-way-sms-in-odoo-with-twilio/)

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)
- [Repository layout](#repository-layout)
- [modules.txt](#modulestxt)
- [pyproject.toml](#pyprojecttoml)
- [odoo.conf](#odooconf)
- [Start working](#start-working)
- [Run the dev server](#run-the-dev-server)
- [Mail never leaves your machine](#mail-never-leaves-your-machine)
- [Live reload](#live-reload)
- [Daily commands](#daily-commands)
- [Add OCA modules](#add-oca-modules)
- [Apply code changes to a database](#apply-code-changes-to-a-database)
- [Upgrade specific modules](#upgrade-specific-modules)
- [Upgrade whatever changed](#upgrade-whatever-changed)
- [Run tests](#run-tests)
- [Everything else](#everything-else)
- [Editor setup](#editor-setup)
- [Start a new project](#start-a-new-project)
- [Troubleshooting](#troubleshooting)

[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/)
