odoorun

odoorun is a portable command-line launcher and inspection tool for Odoo development projects. It discovers the appropriate Odoo executable, prepares addon paths, forwards ordinary Odoo options, completes database and module names, and provides read-only database/addon inspection commands.

No symlink, alias, or machine-specific path is required. Run odoorun completion install once to enable Bash auto-completion.

Features

• Run a project-local odoo-bin, a linked-venv odoo, or odoo on PATH.
• Prefer odoo from the virtual environment active in the current terminal.
• Run from a project root or any nested directory.
• Configure standard and custom addon paths automatically.
• Complete PostgreSQL database names after -d/--database.
• Complete module names after -u/--update and -i/--init.
• Complete odoorun commands, options, and fixed option values.
• List Odoo databases and detect their versions.
• List core/custom addon manifests and optionally show database module state.
• Forward Odoo 19 native module and database management commands.
• Produce human-readable tables, tab-separated text, or JSON.

Requirements

• Python 3.10 or newer.
• psql for database completion, db list, and database-aware addon list.

Launching Odoo and listing addons from the filesystem do not require psql.

Installation

Install the published package as an isolated command:

uv tool install odoorun

Or install with pip:

python -m pip install odoorun

Install the latest source directly from GitHub:

uv tool install git+https://github.com/khalid99io/odoorun.git

Install or refresh a local development checkout:

uv tool install --force .

Quick start

Run Odoo with ordinary Odoo options:

odoorun -d my_database --dev=all
odoorun -d my_database -u sale_management

Add custom directories to an Odoo source checkout. Relative -a paths are resolved from the checkout's parent directory:

odoorun -a custom-addons,enterprise -d my_database

Use Odoo's native addon preference unchanged:

odoorun --addons-path="addons,custom-addons" -d my_database

Use native Odoo 19 module and database commands:

odoorun module uninstall -d my_database obsolete_module
odoorun module upgrade -d my_database sale stock
odoorun db dump my_database backup.zip

The short o command is optional. If you configure alias o=odoorun, the examples below can use o; otherwise use odoorun directly.

How executable discovery works

odoorun selects the first available executor in this order:

1. An executable odoo-bin in the current directory or a parent directory.
2. The odoo executable inside the virtual environment currently active in the terminal through VIRTUAL_ENV.
3. An Odoo executor in the linked or configured project venv, such as ~/venvs/<project>/bin/odoo.
4. An odoo command available on PATH.

When a virtual environment is active, odoorun reads VIRTUAL_ENV and checks that environment directly. Its location and name do not need to match the project directory, and it takes precedence over convention-based lookup.

For source checkouts, the built-in addons directory is passed automatically. For linked-venv projects, --addons-path=odoo/addons is added unless the user provides --addons, --addons-path, or an equivalent value explicitly.

The convention-based lookup remains as a backward-compatible fallback when no suitable active environment is found. If the project and fallback venv names differ, configure it with:

export ODOORUN_VENV_NAME=my-project-venv
export ODOORUN_VENV_ROOT="$HOME/venvs"

odoorun invokes the selected venv executable directly. Activating a venv makes that exact environment the preferred choice; without one, configured discovery and PATH remain available. A child process cannot alter the parent shell prompt, so prompt decoration remains a shell responsibility.

Command reference

Native Odoo commands

Arguments outside odoorun's inspection/setup commands are forwarded to the discovered Odoo executable. This includes Odoo 19's native module commands:

odoorun module install -d my_database module_a module_b
odoorun module upgrade -d my_database module_a module_b
odoorun module uninstall -d my_database module_a module_b

Caution

Uninstalling an Odoo module can delete its records and may uninstall dependent modules. Test against a duplicated database and create a backup before running the command on important data.

It also includes Odoo 19's native database operations:

odoorun db init my_database
odoorun db dump my_database backup.zip
odoorun db load restored_database backup.zip
odoorun db duplicate source_database target_database
odoorun db rename old_name new_name
odoorun db drop my_database

odoorun db list remains odoorun's richer read-only inspection command. Every other db subcommand is delegated to Odoo. Native command availability and exact options therefore depend on the discovered Odoo version.

Odoo passthrough

odoorun [ODOO_OPTIONS]

Arguments whose first item is not an odoorun tool command are passed to the discovered Odoo executable. The -a option is odoorun's source-checkout convenience and is converted into the effective native --addons-path.

odoorun doctor

odoorun doctor

Displays the working directory, active virtual environment, discovered Odoo executable, and whether psql is available. It does not modify the project or start Odoo.

odoorun completion

odoorun completion [bash|install]

• bash prints the generated Bash integration script.
• install idempotently adds source <(odoorun completion bash) to ~/.bashrc.

Run the installer once and open a new Bash terminal:

odoorun completion install

Command and option completion is available for odoorun and o:

o d<Tab>                         # db, doctor
o db <Tab>                       # list, init, dump, load, duplicate, rename, drop
o addon list --s<Tab>            # --source, --state
o addon list --source c<Tab>     # core, custom
o addon list --state in<Tab>     # installed
o db list --format j<Tab>        # json
o module un<Tab>                 # uninstall
o module uninstall -d demo sale_<Tab>
o module force-demo -d demo sale_<Tab>

Database and module completion is also registered for direct Odoo commands: odoo, odoo-bin, and ./odoo-bin.

Database examples:

o -d demo<Tab>
odoorun --database=demo<Tab>

Module examples, including comma-separated values:

o -d my_database -u sale_m<Tab>,bas<Tab>
o -d my_database -i custom_m<Tab>

Database completion uses psql and respects PostgreSQL environment variables such as PGHOST, PGPORT, PGUSER, PGDATABASE, and PGPASSWORD. Module completion finds directories containing __manifest__.py or __openerp__.py in source, project, explicit, and linked-venv addon roots.

odoorun db list

odoorun db list [OPTIONS]

Options:

• --odoo-version VERSION: keep Odoo databases whose installed base module version starts with VERSION, such as 19 or 19.0.
• --all: include regular PostgreSQL and inaccessible databases.
• --format table|plain|json: select the output format; default is table.
• --no-header: hide headings in table/plain output.

Examples:

odoorun db list
odoorun db list --odoo-version 19
odoorun db list --all --format json

By default, only databases recognized as Odoo databases are shown. Detection uses ir_module_module, and the displayed Odoo version comes from the installed base module.

odoorun addon list

odoorun addon list [OPTIONS]

Options:

• -d, --database DATABASE: query ir_module_module and annotate filesystem addons with their state/version in that database.
• --source all|core|custom: filter by addon-root origin.
• --state all|installed|uninstalled|upgrade: filter by database state; non-all values require -d.
• --installed: shortcut for --state installed; requires -d.
• --custom: shortcut for --source custom.
• --core: shortcut for --source core.
• --addons-path PATHS: override discovery with a native comma-separated Odoo addon path.
• -a PATHS: add comma-separated custom directories to source-checkout discovery.
• --format table|plain|json: select the output format; default is table.
• --no-header: hide headings in table/plain output.

Examples:

odoorun addon list
odoorun addon list --source core
odoorun addon list --custom
odoorun addon list -d my_database
odoorun addon list -d my_database --installed --custom
odoorun addon list --addons-path="addons,../enterprise"

Addon discovery always starts from filesystem directories. Supplying -d does not search addons inside a database; it only adds database state/version information and enables state filtering.

odoorun --version

Print the installed odoorun version and exit:

odoorun --version

Every tool command has focused help:

odoorun completion --help
odoorun db list --help
odoorun addon list --help

PostgreSQL connection behavior

Database features execute read-only queries through psql. Standard libpq configuration is respected, including environment variables, service files, and .pgpass. Passwords are not accepted as odoorun command-line options.

Compatibility

The launcher is intentionally decoupled from Odoo's Python package: odoorun discovers and invokes the target project's executable rather than importing Odoo itself. This allows the tool to run source checkouts and virtual environments independently of the Python environment where odoorun is installed.

Capability	Availability
Odoo executable and addon-path discovery	Version-independent
Odoo argument passthrough	Version-independent
doctor, completion, db list, addon list	Provided by odoorun
Native module and extended db subcommands	Odoo 19 or newer

Development

Install development dependencies and run the full local checks:

uv sync --extra dev
uv run ruff format --check src tests
uv run ruff check src tests
uv run python -m unittest discover -s tests -v
uv run python -m compileall -q src tests
uv build

The GitHub CI workflow lints, tests, compiles, and builds the project. The test matrix covers Python 3.10 through 3.14.

See CONTRIBUTING.md for the development workflow and CHANGELOG.md for release history.

License and publishing

odoorun is released under the MIT License. The source repository is:

https://github.com/khalid99io/odoorun

PyPI releases use the GitHub Actions Trusted Publisher workflow. Before a new release, update the version in pyproject.toml, verify CI, and push a matching version tag.