This toolkit contains a few useful tools for Odoo development. The tools are primarily aimed at Odoo employees.
The quickest way to get started is to install the tools using either PyPI:
$ pipx install odoo-toolkitor the GitHub repository directly
$ pipx install --force git+https://github.com/dylankiss/odoo-toolkit.gitTip
You can run any command with the --help option to find out all options you can use.
Tip
Anywhere you can provide modules as arguments or options, you can also use glob patterns to match multiple similar ones.
Usage:
$ otk [OPTIONS] COMMAND [ARGS]...Options:
--install-completion: Install completion for the current shell.--show-completion: Show completion for the current shell, to copy it or customize the installation.--version: Show the version and exit.--help: Show this message and exit.
| Command | Purpose |
|---|---|
otk po export |
Export Odoo translation files (.pot) to each module's i18n folder. |
otk po create |
Create Odoo translation files (.po) according to their .pot files. |
otk po update |
Update Odoo translation files (.po) according to a new version of their .pot files. |
otk po merge |
Merge multiple translation files (.po) into one. |
| Available Languages |
| Command | Purpose |
|---|---|
otk dev start |
Start an Odoo Development Server using Docker and launch a terminal session into it. |
otk dev start-db |
Start a standalone PostgreSQL container for your Odoo databases. |
otk dev stop |
Stop and delete all running containers of the Odoo Development Server. |
| Command | Purpose |
|---|---|
otk tx add |
Add modules to the Transifex config file. |
| Command | Purpose |
|---|---|
otk multiverse |
Set up an Odoo Multiverse environment, having different branches checked out at the same time. |
Work with Odoo Translations (.po and .pot files).
The following commands allow you to export .pot files for Odoo modules, create or update .po files according to their (updated) .pot files, or merge multiple .po files into one.
Export Odoo translation files (.pot) to each module's i18n folder.
This command can autonomously start separate Odoo servers to export translatable terms for one or more modules. A separate server will be started for Community, Community (Localizations), Enterprise, and Enterprise (Localizations) modules with only the modules installed to be exported in that version.
When exporting the translations for base, we install all possible modules to ensure all terms added in by other modules get exported in the base.pot files as well.
You can also export terms from your own running server using the --own-server option and optionally passing the correct arguments to reach your Odoo server.
Note
Without any options specified, the command is supposed to run from within the parent directory where your odoo and enterprise repositories are checked out with these names. Your database is supposed to run on localhost using port 5432, accessible without a password using your current user.
Of course, all of this can be tweaked with the available options. 😉
$ otk po export [OPTIONS] MODULES...e.g.
$ otk po export --db-username odoo --db-password odoo "account_*" mrp saleMODULES...: Export .pot files for these Odoo modules (supports glob patterns), or eitherall,community, orenterprise. [required]
Odoo Server Options:
--start-server / --own-server: Start an Odoo server automatically or connect to your own server. [default:start-server]--full-install: Install every available Odoo module.-c, --com-path PATH: Specify the path to your Odoo Community repository. [default:odoo]-e, --ent-path PATH: Specify the path to your Odoo Enterprise repository. [default:enterprise]-u, --username TEXT: Specify the username to log in to Odoo. [default:admin]-p, --password TEXT: Specify the password to log in to Odoo. [default:admin]--host TEXT: Specify the hostname of your Odoo server. [default:localhost]--port INTEGER: Specify the port of your Odoo server. [default:8069]
Database Options:
-d, --database TEXT: Specify the PostgreSQL database name used by Odoo. [default:__export_pot_db__]--db-host TEXT: Specify the PostgreSQL server's hostname. [default:localhost]--db-port INTEGER: Specify the PostgreSQL server's port. [default:5432]--db-username TEXT: Specify the PostgreSQL server's username.--db-password TEXT: Specify the PostgreSQL user's password.
Options:
--help: Show this message and exit.
Create Odoo translation files (.po) according to their .pot files.
This command will provide you with a clean .po file per language you specified for the given modules. It basically copies all entries from the .pot file in the module and completes the metadata with the right language information. All generated .po files will be saved in the respective modules' i18n directories.
Note
Without any options specified, the command is supposed to run from within the parent directory where your odoo and enterprise repositories are checked out with these names.
$ otk po create [OPTIONS] MODULES...e.g.
$ otk po create -l nl -l fr -l de l10n_be l10n_be_reportsMODULES...: Create .po files for these Odoo modules, or eitherall,community, orenterprise. [required]
-l, --languages LANG: Create .po files for these languages, orall. [default: None] [required]-c, --com-path PATH: Specify the path to your Odoo Community repository. [default:odoo]-e, --ent-path PATH: Specify the path to your Odoo Enterprise repository. [default:enterprise]--help: Show this message and exit.
Update Odoo translation files (.po) according to a new version of their .pot files.
This command will update the .po files for the provided modules according to a new .pot file you might have exported in their i18n directory.
Note
Without any options specified, the command is supposed to run from within the parent directory where your odoo and enterprise repositories are checked out with these names.
$ otk po update [OPTIONS] MODULES...e.g.
$ otk po update -l nl -l fr account account_accountantMODULES...: Update .po files for these Odoo modules, or eitherall,community, orenterprise. [required]
-l, --languages LANG: Update .po files for these languages, orall. [default:all]-c, --com-path PATH: Specify the path to your Odoo Community repository. [default:odoo]-e, --ent-path PATH: Specify the path to your Odoo Enterprise repository. [default:enterprise]--help: Show this message and exit.
Merge multiple translation files (.po) into one.
The order of the files determines which translation takes priority. Empty translations in earlier files will be completed with translations from later files, taking the first one in the order they occur.
If the option --overwrite is active, existing translations in earlier files will always be overwritten by translations in later files. In that case the last file takes precedence.
The .po metadata is taken from the first file by default, or the last if --overwrite is active.
$ otk po merge [OPTIONS] PO_FILES...e.g.
$ otk po merge -o nl_merged.po nl.po nl_BE.poPO_FILES...: Merge these .po files together. [required]
-o, --output-file PATH: Specify the output .po file. [default:merged.po]--overwrite: Overwrite existing translations.--help: Show this message and exit.
When LANG is given as a type, any of the following language codes can be used. They are all available in Odoo.
Tip
When creating new .po files, always try to use the most generic language possible. That way, all more specific languages can fall back on that one.
| Code | Language | Code | Language |
|---|---|---|---|
all |
All languages | he |
Hebrew |
am |
Amharic | hi |
Hindi |
ar |
Arabic | hr |
Croatian |
ar_SY |
Arabic (Syria) | hu |
Hungarian |
az |
Azerbaijani | id |
Indonesian |
be |
Belarusian | it |
Italian |
bg |
Bulgarian | ja |
Japanese |
bn |
Bengali | ka |
Georgian |
bs |
Bosnian | kab |
Kabyle |
ca |
Catalan | km |
Khmer |
cs |
Czech | ko |
Korean |
da |
Danish | ko_KP |
Korean (North Korea) |
de |
German | lb |
Luxembourgish |
de_CH |
German (Switzerland) | lo |
Lao |
el |
Greek | lt |
Lithuanian |
en_AU |
English (Australia) | lv |
Latvian |
en_CA |
English (Canada) | mk |
Macedonian |
en_GB |
English (United Kingdom) | ml |
Malayalam |
en_IN |
English (India) | mn |
Mongolian |
en_NZ |
English (New Zealand) | ms |
Malay |
es |
Spanish | my |
Burmese |
es_419 |
Spanish (Latin America) | nb |
Norwegian Bokmål |
es_AR |
Spanish (Argentina) | nl |
Dutch |
es_BO |
Spanish (Bolivia) | nl_BE |
Dutch (Belgium) |
es_CL |
Spanish (Chile) | pl |
Polish |
es_CO |
Spanish (Colombia) | pt |
Portuguese |
es_CR |
Spanish (Costa Rica) | pt_AO |
Portuguese (Angola) |
es_DO |
Spanish (Dominican Republic) | pt_BR |
Portuguese (Brazil) |
es_EC |
Spanish (Ecuador) | ro |
Romanian |
es_GT |
Spanish (Guatemala) | ru |
Russian |
es_MX |
Spanish (Mexico) | sk |
Slovak |
es_PA |
Spanish (Panama) | sl |
Slovenian |
es_PE |
Spanish (Peru) | sq |
Albanian |
es_PY |
Spanish (Paraguay) | sr |
Serbian |
es_UY |
Spanish (Uruguay) | sr@latin |
Serbian (Latin) |
es_VE |
Spanish (Venezuela) | sv |
Swedish |
et |
Estonian | sw |
Swahili |
eu |
Basque | te |
Telugu |
fa |
Persian | th |
Thai |
fi |
Finnish | tl |
Tagalog / Filipino |
fr |
French | tr |
Turkish |
fr_BE |
French (Belgium) | uk |
Ukrainian |
fr_CA |
French (Canada) | vi |
Vietnamese |
fr_CH |
French (Switzerland) | zh_CH |
Chinese (Simplified) |
gl |
Galician | zh_HK |
Chinese (Hong Kong) |
gu |
Gujarati | zh_TW |
Chinese (Traditional) |
Run an Odoo Development Server using Docker.
The following commands allow you to automatically start and stop a fully configured Docker container to run your Odoo server(s) during development.
Important
These tools require Docker Desktop to be installed on your system.
The Docker container is configured to resemble Odoo's CI or production servers and thus tries to eliminate discrepancies between your local system and the CI or production server.
Start an Odoo Development Server using Docker and launch a terminal session into it.
This command will start both PostgreSQL, Mailhog, and pgAdmin containers, and an Odoo container containing your source code, located on your machine at the location specified by -w. Your specified workspace will be sourced in the container at the location /code and allows live code updates during local development.
You can choose to launch a container using Ubuntu 24.04 [-u noble] (default, recommended starting from version 18.0) or 22.04 [-u jammy] (for earlier versions).
When you're done with the container, you can exit the session by running the exit command. At this point, the container will still be running and you can start a new session using the same otk dev start command.
The jammy container exposes ports 8070, 8071, 8072, 8073 and 8074. The default port inside the container when using the o-bin-* commands, is 8070. When not using the o-bin-* commands, or when starting another server, you need to use the --http-port option to run on one of the available ports.
The noble container exposes ports 8075, 8076, 8077, 8078 and 8079. The default port inside the container when using the o-bin-* commands, is 8075. When not using the o-bin-* commands, or when starting another server, you need to use the --http-port option to run on one of the available ports.
This allows you to run up to 5 different servers per Docker container, all accessible on your local machine. If you also have a local server running on default port 8069, it will not clash with the Docker ports.
The command starts a separate PostgreSQL container that you can access from your host machine at localhost:5432 by default, using odoo as username and no password. Inside your other Docker containers, the hostname of this server is postgres. It is exposed to the Odoo containers via a socket as well in the /var/run/postgresql directory.
The command starts a Mailpit container that is used for intercepting outgoing email messages from any of your Odoo instances. The application can be accessed from your local machine by going to http://localhost:8025. It allows you to view any sent email with its attachments and all possible related information. You can download them in .eml format, .html format, and even .png format as a screenshot.
The container uses a persistent storage (on the odoo-mailpit-storage volume) that saves up to 5000 messages. The oldest messages will be deleted after that. When the volume is deleted, all messages will be gone as well.
The command starts a pgAdmin container that you can use to inspect and interact with the databases in the PostgreSQL container. The application can be accessed from your local machine by going to http://localhost:5050. When you connect to the PostgreSQL server for the first time, pgAdmin will ask for a password. You can just leave this empty.
The container contains some helpful aliases that you can use to run and debug Odoo from your workspace (either /code or /code/<branch> if you're using the multiverse setup). They contain some default configuration and set very high time limits by default (useful for debugging). You can check them in .bash_aliases.
Running Odoo (from within the workspace folder)
o-bincan be used instead ofodoo/odoo-binwith the same arguments.
Running an Odoo shell (from within the workspace folder)
o-bin-shcan be used instead ofodoo/odoo-bin shellwith the same arguments.
Upgrading Odoo (from within the workspace folder)
o-bin-upcan be used instead ofodoo/odoo-bin --upgrade-path=...with the same arguments.
Debugging Odoo (from within the workspace folder)
o-bin-debcan be used instead ofodoo/odoo-binwith the same arguments, starts a debug session usingdebugpyand waits for your local debugger to connect to it before starting.
Debugging Odoo Upgrade (from within the workspace folder)
o-bin-deb-upcan be used instead ofodoo/odoo-bin --upgrade-path=...with the same arguments, starts a debug session usingdebugpyand waits for your local debugger to connect to it before starting.
Tip
Every alias can be appended by -c or -e to have the addons paths for respectively Community or Enterprise (e.g. o-bin-deb-up-c).
Tip
Compatible Visual Studio Code debug configurations are available in launch.json.
The most common PostgreSQL commands have also been aliased to use the right database and credentials, so you could just run e.g. dropdb <database>.
The configuration for the Docker containers is located in the odoo_toolkit/docker folder in this repository. The compose.yaml file defines an odoo-noble and odoo-jammy service that run the development containers with the right configuration and file mounts, and a postgres, mailpit, and pgadmin service that run the PostgreSQL server, the Mailpit server, and the pgAdmin server respectively.
The development container configuration is laid out in noble.Dockerfile and jammy.Dockerfile.
$ otk dev start [OPTIONS]e.g.
$ otk dev start -u jammy-w, --workspace PATH: Specify the path to your development workspace that will be mounted in the container's/codedirectory. [default:~/code/odoo]-u, --ubuntu-version [noble|jammy]: Specify the Ubuntu version to run in this container. [default:noble]-p, --db-port INTEGER: Specify the port on your local machine the PostgreSQL database should listen on. [default:5432]--build: Build the Docker image locally instead of pulling it from DockerHub.--help: Show this message and exit.
Start a standalone PostgreSQL container for your Odoo databases.
You can use this standalone container if you want to connect to it from your local machine which is running Odoo. By default it will listen on port 5432, but you can modify this if you already have another PostgreSQL server running locally.
$ otk dev start-db [OPTIONS]-p, --port INTEGER: Specify the port on your local machine the PostgreSQL database should listen on. [default:5432]--help: Show this message and exit.
Stop and delete all running containers of the Odoo Development Server.
This is useful if you want to build a new version of the container, or you want the container to have the latest version of odoo-toolkit.
Running this is also necessary if you updated the odoo-toolkit package on your local machine. If not, your container won't be able to mount the configuration files.
$ otk dev stop [OPTIONS]--help: Show this message and exit.
Work with Transifex.
The following commands allow you to modify the Transifex config files.
Add modules to the Transifex config file.
This command will add module entries to .tx/config files. The .tx/config files need to be located at the provided
addons paths' roots. If the entries already exists, they will potentially be updated.
For odoo and enterprise, the project name follows the format odoo-18 for major versions and odoo-s18-1 for SaaS
versions. Other repos have their own project names.
$ otk tx add [OPTIONS] MODULES...e.g.
$ otk tx add -p odoo-18 -a design-themes theme_*MODULES...: Add these Odoo modules to.tx/config, or eitherall,community, orenterprise. [required]
-p, --tx-project TEXT: Specify the Transifex project name. [required]-o, --tx-org TEXT: Specify the Transifex organization name. [default:odoo]-c, --com-path PATH: Specify the path to your Odoo Community repository. [default:odoo]-e, --ent-path PATH: Specify the path to your Odoo Enterprise repository. [default:enterprise]-a, --addons-path PATH: Specify extra addons paths if your modules are not in Community or Enterprise.--help: Show this message and exit.
Set up an Odoo Multiverse environment, having different branches checked out at the same time.
This way you can easily work on tasks in different versions without having to switch branches, or easily compare behaviors in different versions.
The setup makes use of the git worktree feature to prevent having multiple full clones of the repositories for each version. The git history is only checked out once, and the only extra data you have per branch are the actual source files.
The easiest way to set this up is by creating a directory for your multiverse setup and then run this command from that directory.
Important
Make sure you have set up your GitHub SSH key beforehand in order to clone the repositories.
You can run the command as many times as you want. It will skip already existing branches and repositories and only renew their configuration (when passed the --reset-config option).
Tip
If you're using Visual Studio Code, you can use the --vscode option to have the script copy some default configuration to each branch folder. It contains recommended plugins, plugin configurations and debug configurations (that also work with the Docker container started via otk dev start).
The command will basically do the following:
-
Clone the repositories that have multiple active branches (among
odoo,enterprise,design-themes,documentation,industryando-spreadsheet) as bare repositories to a.multiverse-source/<repository>folder (we don't need the source files themselves here). We set them up in a way that we can correctly create worktrees for each branch. We add the remoteorigin(git@github.com:odoo/<repository>.git) for all repositories and the remotedev(git@github.com:odoo-dev/<repository>.git) for all except thedocumentationando-spreadsheetrepositories. -
Clone the single-branch repositories (among
upgrade,upgrade-util,odoofinandinternal) to the root of your multiverse directory. -
Create a directory per branch in your multiverse directory, and a directory per multi-branch repository inside each branch directory. We use
git worktree addto add a worktree for the correct branch for each repository. -
Create a symlink to each single-branch repository in each branch directory, since they all use the same
masterbranch of these repositories. -
Copy all configuration files into each branch directory and set up the Javascript tooling for
odooandenterprise(located in thetoolingdirectory inside thewebmodule). -
Set up a Python virtual environment (
venv) in the.venvdirectory inside each branch directory and install all requirements ofodooanddocumentation, as well as the recommended ones inrequirements.txt. You can use this environment from the branch directory usingsource .venv/bin/activate.
After all that is done, your directory structure should look like this with the default repositories selected:
<multiverse-folder>
├── .worktree-source
│ ├── odoo (bare)
│ ├── enterprise (bare)
│ └── design-themes (bare)
├── 16.0
│ └── ...
├── 17.0
│ └── ...
├── saas-17.2
│ └── ...
├── saas-17.4
│ └── ...
├── 18.0
│ ├── .venv (Python virtual environment)
│ ├── odoo (18.0)
│ ├── enterprise (18.0)
│ ├── design-themes (18.0)
│ ├── upgrade (symlink to ../upgrade)
│ ├── upgrade-util (symlink to ../upgrade-util)
│ ├── pyproject.toml
│ └── requirements.txt
├── master
│ └── ...
├── upgrade (master)
└── upgrade-util (master)
$ otk multiverse [OPTIONS]e.g.
$ otk multiverse -b 16.0 -b 17.0 -b 18.0 -r odoo -r enterprise -r upgrade -r upgrade-util --vscode-b, --branches TEXT: Specify the Odoo branches you want to add. [default:16.0,17.0,saas-17.2,saas-17.4,18.0,master]-r, --repositories REPO: Specify the Odoo repositories you want to sync. [default:odoo,enterprise,design-themes,upgrade,upgrade-util]-d, --multiverse-dir PATH: Specify the directory in which you want to install the multiverse setup. [default:<current working directory>]--reset-config: Reset every specified worktree's Ruff config, Python virtual environment and dependencies, and optional Visual Studio Code config.--vscode: Copy settings and debug configurations for Visual Studio Code.--help: Show this message and exit.
REPO can be any of these repositories: