How to Install a Custom Module in Odoo

Odoo's built-in apps don't always cover a business process, so teams add custom modules. This guide shows how to install one on your own server or on Odoo.sh, what you can and can't do on Odoo Online, and how to fix the errors people hit most often. Need a module built first? See our custom Odoo module development page.

Before You Start

• Match the Odoo version. The module must be built for your Odoo version. Check the version key in its __manifest__.py (for example 17.0.1.0.0).
• Install dependencies. Install any Odoo modules listed under depends in the manifest, and any Python packages the module needs.
• Back up your database. Do this before you install anything.
• Test on a staging copy first, never straight on your live system.

Install on Your Own Server (On-Premise)

Step 1: Copy the module to your addons folder

Copy the module folder into your custom addons folder, for example /opt/odoo/custom-addons/. The module folder must contain __init__.py and __manifest__.py. If the folder doesn't exist yet, create it first.

sudo mkdir -p /opt/odoo/custom-addons
scp -r my_module user@your-server:/tmp/
sudo mv /tmp/my_module /opt/odoo/custom-addons/

Step 2: Set the owner so Odoo can read it

sudo chown -R odoo:odoo /opt/odoo/custom-addons/

Replace odoo:odoo with the user and group your Odoo service runs as.

Step 3: Add the folder to addons_path

Open odoo.conf (often /etc/odoo.conf) and add your folder to addons_path, separated by a comma from the existing paths.

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

Step 4: Restart Odoo

sudo systemctl restart odoo

Use the service name your server uses if it is not odoo.

Step 5: Turn on developer mode

Go to Settings → Activate the developer mode. You can also add ?debug=1 to the URL, for example https://your-odoo.com/odoo?debug=1.

Step 6: Update the apps list

Go to Apps → Update Apps List and confirm.

Step 7: Find and install the module

In the Apps menu, remove the default Apps filter from the search bar, search for your module by name, and click Activate (called Install in older versions).

Step 8: Check that it works

Open the new menus or features the module adds, and check the Odoo log for errors.

sudo tail -f /var/log/odoo/odoo-server.log

Your log path may differ. It is set by logfile in odoo.conf.

Optional: install from the command line

You can also install a module without the web interface. Use -i to install and -u to upgrade it later. --stop-after-init makes Odoo exit when it is done.

# install
odoo-bin -c /etc/odoo.conf -d your_db -i module_name --stop-after-init

# upgrade after you change the module
odoo-bin -c /etc/odoo.conf -d your_db -u module_name --stop-after-init

Use odoo instead of odoo-bin if you installed Odoo from a package.

Install on Odoo.sh

Step 1: Add the module to your GitHub repository

Put the module folder in your project's repository, on a staging branch first.

git checkout staging
git add my_module/
git commit -m "Add my_module"

Step 2: Push the branch

git push origin staging

Odoo.sh builds the branch automatically.

Step 3: Install it on the staging build

Open the staging build, update the apps list and install the module, as in steps 5 to 7 above.

Step 4: Merge to production

When testing is done, merge the branch into your production branch.

What About Odoo Online?

Odoo Online (the standard cloud plan) doesn't allow custom Python modules, so the steps above don't work there.

• You can use Studio for no-code changes, and import data-only modules.
• If you need custom code, you'll need Odoo.sh or your own server.

Common Errors and How to Fix Them

Custom Module Install FAQs

Can I install a custom module on Odoo Online?

No. Odoo Online (the standard cloud plan) does not allow custom Python modules. You can use Studio for no-code changes. If you need custom code, move to Odoo.sh or your own server.

Where do I put custom modules in Odoo?

Put them in a separate custom addons folder, for example /opt/odoo/custom-addons/, and add that folder to addons_path in odoo.conf. Do not put custom modules inside Odoo's own addons folder.

Why doesn't my module show in the Apps list?

The most common causes are a wrong addons_path, Odoo not restarted, the apps list not updated, or the Apps filter still active in the search bar. Also check that the module folder contains __init__.py and __manifest__.py.

How do I update a custom module after changing it?

Restart Odoo, then upgrade the module from the Apps menu, or run Odoo from the command line with -u module_name. On Odoo.sh, push your change to the branch and upgrade the module on that build.

Will my custom module work after an Odoo upgrade?

Not always. A module built for an older Odoo version usually needs to be migrated and tested before it works on a newer one. Check the version in __manifest__.py and test on a staging copy first.