How to Install Custom Modules in Odoo

Odoo's power comes from its modular architecture. Beyond the official App Store, you can install community modules, third-party packages, or your own custom code. This guide walks through every method: configuring addons_path, using the Apps menu, deploying via Git, and managing Python dependencies.

What Is an Odoo Custom Module?

A custom module is any Python package that follows Odoo's module structure — a directory containing __manifest__.py and __init__.py. Odoo discovers modules by scanning one or more directories listed in addons_path inside odoo.conf. When Odoo starts, it builds an in-memory registry of every module it finds.

Step 1 — Configure addons_path

Open your Odoo configuration file (commonly /etc/odoo/odoo.conf or ~/.odoorc) and locate the addons_path line. Add the path to your custom modules directory:

[options]
addons_path = /opt/odoo/odoo/addons,/opt/odoo/enterprise,/opt/odoo/custom

Paths are comma-separated. Odoo scans them left to right, and the last match wins if two modules share the same technical name. Create your custom directory and make sure the Odoo system user has read access:

sudo mkdir -p /opt/odoo/custom
sudo chown odoo:odoo /opt/odoo/custom

Restart Odoo after any change to odoo.conf for the new path to take effect.

Step 2 — Update the Apps List

Odoo caches the module list in the database. After placing a new module on disk, you must tell Odoo to rescan:

1. Activate developer mode: go to Settings → General Settings, scroll to the bottom, and click Activate the developer mode.
2. Navigate to Apps → Update Apps List.
3. Click Update in the dialog that appears.

Odoo will scan every directory in addons_path and register newly discovered modules.

Step 3 — Install from the Apps Menu

Once the list is updated, search for your module by its technical name or display name in the Apps menu. Remove the Apps filter if you want to see all module categories, then click Install. Odoo will resolve dependencies and install them in the correct order.

To install from the command line (useful in CI pipelines or during initial setup):

odoo -d mydb -i my_custom_module --stop-after-init

To upgrade an already-installed module:

odoo -d mydb -u my_custom_module --stop-after-init

Step 4 — Git Clone Method

For team environments and repeatable deployments, store your modules in Git and clone them into the addons_path directory:

# Clone a community module from OCA
cd /opt/odoo/custom
git clone https://github.com/OCA/server-tools.git oca_server_tools

# Or clone your private repo using an SSH deploy key
git clone [email protected]:yourorg/your-odoo-modules.git private_modules

After cloning, update the Apps list and install as described above. For automated deployments, see our guide on Odoo Git deployment workflows.

Step 5 — Handling pip Dependencies

Some modules declare Python package requirements in their __manifest__.py under the external_dependencies key:

'external_dependencies': {
'python': ['boto3', 'requests-oauthlib'],
},

Install these packages into the same Python environment that runs Odoo:

# If using a virtualenv
source /opt/odoo/venv/bin/activate
pip install boto3 requests-oauthlib

# If running in Docker
docker exec -u root odoo_container pip install boto3 requests-oauthlib

For Docker-based deployments, the cleanest approach is to extend the official Odoo image with a custom Dockerfile that pre-installs your dependencies, so they survive container restarts and image updates.

Troubleshooting Common Issues

• Module not visible after Update Apps List: Check that the directory contains both __manifest__.py and __init__.py. A missing __init__.py causes silent failure.
• ImportError on startup: A required pip package is missing. Check Odoo logs at /var/log/odoo/odoo.log.
• Version mismatch: Ensure the module's version field in __manifest__.py starts with your Odoo major version (e.g., 17.0.1.0.0).
• Conflicting module names: Two modules with the same technical name in different addons_path entries. The last path wins; rename one module to resolve.

Installing Custom Modules on DeployMonkey

DeployMonkey makes custom module installation straightforward on managed Odoo hosting:

• Git integration: Connect your module repository directly from the Instance Settings panel. DeployMonkey pulls your repo and mounts it automatically into the container's addons path.
• No SSH required: Deploy key management is handled by the platform — no manual key exchange needed.
pip dependencies: List your Python requirements in a requirements.txt at the root of your repo. DeployMonkey installs them during every deployment.
• One-click upgrade: After pushing a new commit, trigger a module upgrade from the dashboard without restarting the entire instance.
• All Odoo versions supported: Modules for Odoo 14 through 19 are supported on all plans, including the free tier.

Learn more about Git-based module deployment in our Odoo Git deployment guide.

FAQ

Ready to Deploy Custom Modules Without the Headache?

DeployMonkey handles the infrastructure so you can focus on building. Git-connected deployments, automatic pip dependency installation, and one-click module upgrades are included on every plan — starting free. See plans and pricing or start your free instance today.