{"id":9302,"library":"setuptools-odoo","title":"setuptools-odoo","description":"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.","status":"active","version":"3.3.2","language":"en","source_language":"en","source_url":"https://github.com/acsone/setuptools-odoo","tags":["odoo","setuptools","packaging","addons","distribution"],"install":[{"cmd":"pip install setuptools-odoo","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency, extended by this library. Explicitly pinned for compatibility.","package":"setuptools","optional":false}],"imports":[{"note":"Use setuptools_odoo.find_packages for Odoo addon specific package discovery, as it handles manifest files.","wrong":"from setuptools import find_packages","symbol":"find_packages","correct":"from setuptools_odoo import find_packages"},{"note":"Required to enable Odoo-specific packaging features like the 'odoo_addons' option in setup().","symbol":"OdooDistribution","correct":"from setuptools_odoo.dist import OdooDistribution"}],"quickstart":{"code":"# pyproject.toml\n[build-system]\nrequires = [\"setuptools>=61.0.0\", \"setuptools-odoo~=3.3.0\", \"wheel\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"my_odoo_addon\"\nversion = \"1.0.0\"\ndescription = \"My custom Odoo addon\"\nauthors = [\n    {name = \"Your Name\", email = \"your@example.com\"}\n]\nreadme = \"README.md\"\nlicense = {text = \"MIT\"}\nrequires-python = \">=3.8\"\nclassifiers = [\n    \"Framework :: Odoo\",\n    \"Framework :: Odoo :: 16.0\",\n    \"License :: OSI Approved :: MIT License\",\n    \"Programming Language :: Python :: 3.8\",\n    \"Programming Language :: Python :: 3.9\",\n    \"Programming Language :: Python :: 3.10\"\n]\ndependencies = [\n    # Add your Odoo module dependencies here, e.g., 'odoo>=16.0.0'\n]\n\n# setup.py (optional, but needed for specific Odoo options)\nimport setuptools\nfrom setuptools_odoo import find_packages, OdooDistribution\n\nif __name__ == '__main__':\n    setuptools.setup(\n        name=\"my_odoo_addon\",\n        version=\"1.0.0\", # Should match pyproject.toml\n        distclass=OdooDistribution,\n        packages=find_packages(),\n        include_package_data=True,\n        odoo_addons=True, # Enable Odoo addon specific packaging\n        # odoo_addon_dir='my_addon_dir', # Optional: if your addon is not at root\n        zip_safe=False,\n    )\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your project's `pyproject.toml` or `setup.py` build requirements explicitly pin `setuptools<82` (e.g., `setuptools~=69.0`).","message":"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.","severity":"breaking","affected_versions":">=3.3.2"},{"fix":"Always include `setuptools-odoo` in the `build-system.requires` section of your `pyproject.toml`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"In your `setup.py`, ensure your `setuptools.setup()` call includes `distclass=OdooDistribution`, `include_package_data=True`, and `odoo_addons=True`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Import `OdooDistribution` from `setuptools_odoo.dist` and pass `distclass=OdooDistribution` to your `setuptools.setup()` call.","cause":"Attempting to use the `odoo_addons=True` parameter in `setuptools.setup()` without configuring `distclass=OdooDistribution`.","error":"RuntimeError: The 'odoo_addons' option requires 'OdooDistribution' as distclass."},{"fix":"Add `setuptools-odoo` to the `build-system.requires` section in your `pyproject.toml` (e.g., `requires = [\"setuptools-odoo~=3.3.0\"]`).","cause":"`setuptools-odoo` is not installed in the build environment, or not properly declared as a build dependency.","error":"ModuleNotFoundError: No module named 'setuptools_odoo'"},{"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'`.","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.","error":"distutils.errors.FileError: The following data files are missing: [...]"},{"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.","cause":"An issue with the `setuptools-odoo-makedefault` command-line utility, specifically a `FileNotFoundError` during execution, often on Windows or with older versions.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'dist-info/setuptools-odoo-makedefault'"}]}