Installing OCA modules on self-hosted Odoo

What OCA modules are

The Odoo Community Association (OCA) is a non-profit that coordinates open-source development around Odoo. Its members maintain modules for accounting, reporting, stock, HR, website, server tools and much more, many of which fill gaps between Odoo Community and Enterprise.

The modules are free and the code is public. Like any open-source project, quality varies from module to module, so a little checking before you install pays off.

How OCA repositories are organised

One repository per theme

Instead of one repository per module, the OCA groups related modules into themed repositories on GitHub, such as web, server-tools, account-financial-tools or stock-logistics-workflow. Each repository contains many modules, each in its own folder.

One branch per Odoo version

Each repository has a branch per Odoo series: 17.0, 18.0, 19.0 and so on. A module only exists on a branch once it has been migrated to that version. Newer versions take time to catch up, so if you depend on several OCA modules, check that all of them exist for your target version before you upgrade Odoo.

Dependencies between repositories

A module in one repository often depends on modules in another. Each OCA repository lists the other OCA repositories it needs in a file called oca_dependencies.txt at its root. Those repositories may have dependencies of their own, so follow the list until nothing new appears.

Choosing an OCA module

Where to find modules

Start from the problem, not the module name. Three places help:

• The OCA's app store at apps.odoo-community.org, where you can search modules by name and read their descriptions and READMEs.
• GitHub search across the OCA organisation, useful when you know part of a technical name, such as mis_builder or account_reconcile.
• Each repository's README, which lists the modules on that branch with a short summary of what each one does.

Before you pick one, write down the exact Odoo series you run, because availability differs between branches.

Maturity level

Each OCA module declares a development status in its manifest: Alpha, Beta, Production/Stable or Mature. Alpha and Beta modules can change, or have known gaps, so test them carefully before using them in production.

Licence

Most OCA modules are licensed under the AGPL-3, and some under the LGPL-3; each module's manifest states its licence. According to the OCA's FAQ, the AGPL has consequences for proprietary modules that depend on AGPL modules. If you distribute or sell modules of your own, check the licences of everything they depend on.

Signs of a healthy module

• A README that explains configuration and usage.
• Recent commits and named maintainers on the branch you need.
• Few open issues that describe problems like yours.

How to install OCA modules step by step

These steps assume Odoo runs from source on your own server, as in our guide to self-hosting Odoo Community.

1. Clone the repository on the right branch, outside the Odoo source tree:

   sudo -u odoo git clone --depth 1 -b 19.0 --single-branch \
     https://github.com/OCA/web /opt/odoo/oca/web

2. Clone its dependencies from oca_dependencies.txt, on the same branch.
3. Install Python requirements. If a repository has a requirements.txt, install it into Odoo's virtual environment:

   sudo -u odoo /opt/odoo/venv/bin/pip install -r /opt/odoo/oca/web/requirements.txt

4. Add every repository to the addons path in odoo.conf, separated by commas:

   addons_path = /opt/odoo/odoo/addons,/opt/odoo/oca/web,/opt/odoo/addons

5. Restart Odoo so it sees the new modules.
6. Install the module: update the apps list in developer mode and install it from the Apps menu, or from the command line with -i module_name.

Do this on a staging copy first. Some modules change how existing screens work, and uninstalling a module later does not always remove everything it added. Our article on Odoo staging environments explains how to test safely.

Keeping OCA modules up to date

• Pull regularly on the same branch to get bug fixes, then restart Odoo and update the changed modules with -u.
• Know which commit you run. Keeping OCA repositories as Git checkouts means you can see what changed and go back to the previous commit if an update breaks something.
• Fork when you need a fix early. If you need a fix that is not merged yet, fork the repository, apply it, and point your server at your fork until the fix lands upstream.

The same Git workflow works for your own modules; see deploying Odoo custom modules from Git.

Common OCA installation problems

• The module does not appear in Apps: its repository is not on the addons path, Odoo was not restarted, or the apps list was not updated.
• "Unmet dependencies": a module it depends on lives in another OCA repository you have not cloned. Check oca_dependencies.txt.
• Import errors in the log: a Python package is missing. Install the repository's requirements into the same virtual environment Odoo runs in.
• Wrong version: a module cloned from the 18.0 branch will not install on Odoo 19. Use the branch that matches your Odoo series.

OCA modules on CloudPilot

CloudPilot does these steps for you on every plan:

• A Marketplace of OCA addons for each instance's Odoo version, with each addon's maturity, licence and source link shown.
• Dependencies handled. When you install an addon, CloudPilot adds its OCA repository and those of the addons it depends on, on the matching branch, installs their Python requirements, puts them on the addons path and installs the addon.
• Updates from Git. Added repositories appear with your other Git modules, so you can update them, turn on automatic upgrades or remove them.
• Any OCA repository or fork can also be added by URL and branch.

See Install OCA addons from the Marketplace for the steps, Odoo Community hosting for the rest of the platform, and pricing for each plan.

OCA modules: questions