setuptools-odoo

3.3.2 · active · verified Thu Apr 16

setuptools-odoo is a Python library that extends setuptools to simplify packaging and distribution of Odoo addons. It handles specific Odoo addon file structures and metadata, ensuring that module manifest files, static assets, and other Odoo-specific components are correctly included in Python packages. The current version is 3.3.2, with a fairly active release cadence primarily for compatibility updates and core addon list refreshes.

Common errors

```
RuntimeError: The 'odoo_addons' option requires 'OdooDistribution' as distclass.
```
cause Attempting to use the `odoo_addons=True` parameter in `setuptools.setup()` without configuring `distclass=OdooDistribution`.

fix Import `OdooDistribution` from `setuptools_odoo.dist` and pass `distclass=OdooDistribution` to your `setuptools.setup()` call.
```
ModuleNotFoundError: No module named 'setuptools_odoo'
```
cause `setuptools-odoo` is not installed in the build environment, or not properly declared as a build dependency.

fix Add `setuptools-odoo` to the `build-system.requires` section in your `pyproject.toml` (e.g., `requires = ["setuptools-odoo~=3.3.0"]`).
```
distutils.errors.FileError: The following data files are missing: [...]
```
cause Odoo-specific data files (like XML, JS, CSS, or manifest files) are not being included in the package. This often happens if `odoo_addons=True` or `include_package_data=True` is missing, or `odoo_addon_dir` is incorrect.

fix Verify that your `setuptools.setup()` call includes `odoo_addons=True` and `include_package_data=True`. If your addon is not directly in the root, specify `odoo_addon_dir='your_addon_path'`.
```
FileNotFoundError: [Errno 2] No such file or directory: 'dist-info/setuptools-odoo-makedefault'
```
cause An issue with the `setuptools-odoo-makedefault` command-line utility, specifically a `FileNotFoundError` during execution, often on Windows or with older versions.

fix Upgrade `setuptools-odoo` to version `3.2.1` or newer, as this issue was addressed in that release. Ensure you are using a compatible Python and `setuptools` version.

Warnings

breaking Version 3.3.2 explicitly pins `setuptools<82`. Using `setuptools-odoo` with `setuptools` versions 82 or higher will lead to build errors due to incompatibilities.
Fix: Ensure your project's `pyproject.toml` or `setup.py` build requirements explicitly pin `setuptools<82` (e.g., `setuptools~=69.0`).
gotcha For new projects, defining `setuptools-odoo` in `build-system.requires` in `pyproject.toml` is the modern and recommended approach. Relying on `setup_requires` directly in `setup.py` is considered legacy and may lead to issues with newer Python packaging tools.
Fix: Always include `setuptools-odoo` in the `build-system.requires` section of your `pyproject.toml`.
gotcha When using `odoo_addons=True` in `setup()`, it is crucial to also set `include_package_data=True` and ensure that `distclass=OdooDistribution` is specified. Failure to do so can result in missing manifest files, static assets, or other Odoo-specific data in your packaged distribution.
Fix: In your `setup.py`, ensure your `setuptools.setup()` call includes `distclass=OdooDistribution`, `include_package_data=True`, and `odoo_addons=True`.

Install

pip install setuptools-odoo Install latest version

Imports

find_packages
wrong:
```
from setuptools import find_packages
```
correct:
```
from setuptools_odoo import find_packages
```
Use setuptools_odoo.find_packages for Odoo addon specific package discovery, as it handles manifest files.
OdooDistribution
```
from setuptools_odoo.dist import OdooDistribution
```
Required to enable Odoo-specific packaging features like the 'odoo_addons' option in setup().

Quickstart

To package an Odoo addon with setuptools-odoo, you typically define your build system in `pyproject.toml` and optionally use a `setup.py` for advanced `setuptools-odoo` specific configurations. The example demonstrates setting up `build-system` requirements in `pyproject.toml` and a basic `setup.py` that utilizes `OdooDistribution` and `odoo_addons=True` to correctly package an Odoo module.

# pyproject.toml
[build-system]
requires = ["setuptools>=61.0.0", "setuptools-odoo~=3.3.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my_odoo_addon"
version = "1.0.0"
description = "My custom Odoo addon"
authors = [
    {name = "Your Name", email = "your@example.com"}
]
readme = "README.md"
license = {text = "MIT"}
requires-python = ">=3.8"
classifiers = [
    "Framework :: Odoo",
    "Framework :: Odoo :: 16.0",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3.8",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10"
]
dependencies = [
    # Add your Odoo module dependencies here, e.g., 'odoo>=16.0.0'
]

# setup.py (optional, but needed for specific Odoo options)
import setuptools
from setuptools_odoo import find_packages, OdooDistribution

if __name__ == '__main__':
    setuptools.setup(
        name="my_odoo_addon",
        version="1.0.0", # Should match pyproject.toml
        distclass=OdooDistribution,
        packages=find_packages(),
        include_package_data=True,
        odoo_addons=True, # Enable Odoo addon specific packaging
        # odoo_addon_dir='my_addon_dir', # Optional: if your addon is not at root
        zip_safe=False,
    )

view raw JSON →