Build Types¶

Polytropos supports three build types for different use cases. For more details on Python packaging formats, see the Python Packaging User Guide.

Editable Install¶

Use editable installs for local development. The module code stays in place, and a .pth file points Python to your source directory.

Installation¶

uv add --editable ./addon --config-setting odoo_release=19.0

How It Works¶

Polytropos generates __manifest__.py at install time based on the specified Odoo release. The manifest is written directly to your source directory.

A .pth file is placed in the wheel pointing to a directory that contains a symlink structure mapping odoo/addons/{module_name} to your source directory. This directory lives outside your project tree by default, so Odoo's addons discovery never walks it.

The cache directory name includes the module name, version, and a hash of the absolute addon path (e.g. odoo_addon_my_module-19.0.1.0.0-a1b2c3d4e5f6), making it human-identifiable while staying unique per source location.

Broken symlinks are cleaned up automatically at most once per hour, when a new editable build is triggered.

Environment Variables¶

Variable	Purpose
`POLYTROPOS_CACHE_DIR`	Override the base directory for the Polytropos cache (default: `/var/cache/polytropos/` when writable, `$XDG_CACHE_HOME/polytropos/` otherwise, or `~/.cache/polytropos/` as fallback). Editable install symlinks are placed in a `editable/` subdirectory within this path.
`POLYTROPOS_EDITABLE_IN_SOURCE`	If set, use `build/__editable__/` inside the project (legacy behavior)

Limitations¶

You cannot test two Odoo releases in parallel with editable installs, since each would generate a different __manifest__.py in the same location. If you need to test multiple releases simultaneously, either:

Clone the module into separate folders and install each in editable mode
Use wheels instead

Gitignore¶

Add __manifest__.py and PKG-INFO to your module's .gitignore to prevent accidentally committing generated files:

.gitignore

__manifest__.py
PKG-INFO

__manifest__.py: The generated manifest, regenerated at build time for the target release
PKG-INFO: Metadata file required for editable installs

Source Distribution (sdist)¶

Use sdist for distribution via PyPI or when you need a portable source package. See Creating source distributions.

Build¶

uv build --sdist

This produces a .tar.gz file in the dist/ directory.

Info

You always need to pass --sdist explicitly!

Version¶

The sdist version is just the module version (e.g., 1.2.3), not release.module_version (e.g., 18.0.1.2.3). This is intentional: an sdist serves as a build artifact that can be used to build a wheel for any release.

How It Works¶

Polytropos produces a tarball containing the module source code, without any __manifest__.py file.

Binary Distribution (bdist/wheel)¶

Use wheel (bdist) for installing the module as a proper Python package. See Building Python wheels.

Build¶

uv build --wheel --config-setting odoo_release=17.0

This produces a .whl file in the dist/ directory.

Info

You always need to pass --wheel explicitly!

Version¶

The wheel version is the combination of the Odoo release + module version (e.g., 19.0.1.2.3). The wheel is only compatible with that release.

How It Works¶

The wheel contains:

The module code
The generated __manifest__.py for the specified release
Metadata from pyproject.toml

Src Layout¶

By default, Polytropos expects module files at the project root. Use the src option to place them in a subdirectory:

pyproject.toml

[tool.polytropos]
default_odoo_release = "18.0"
src = "src"

[[tool.polytropos.manifest]]
data = [
    "security/ir.model.access.csv",
]

📄 pyproject.toml
📁 src/
  📄 __init__.py
  📁 models/
    📄 __init__.py
    📄 my_model.py
  📁 security/
    📄 ir.model.access.csv

The src option applies to wheel and editable builds. The sdist always includes the full project tree.