Odoo Module Not Loadable With Traceback — Startup Fix Guide

You start Odoo and the entire process dies during module load with a Python traceback like:

ERROR: Failed to load module 'sale_extension'
Traceback (most recent call last):
  File "/opt/odoo/odoo/modules/loading.py", line 482, in load_modules
    load_module_graph(...)
  File "/opt/odoo/custom/sale_extension/models/sale_priority.py", line 7, in <module>
    from odoo.addons.sale_subscription.models.sale_order import SaleOrder
ModuleNotFoundError: No module named 'odoo.addons.sale_subscription'

The server never finishes booting. Existing users are locked out the moment workers restart. This is a hard module-load failure on Odoo 17.0/18.0/19.0 — fixable in minutes once you know which of the five common roots you hit.

Quick Fix

The traceback names the failing line. Read up to five lines before and after it. Most failures are one of:

# Cause 1: missing dependency
'depends': ['sale', 'sale_subscription'],   # add the missing module to manifest

# Cause 2: typo in import
from odoo.addons.sale_subscription.models.sale_order import SaleOrder   # was: sale_subscritpion

# Cause 3: addons_path missing the directory
# odoo.conf:
addons_path = /opt/odoo/addons,/opt/odoo/enterprise,/opt/odoo/custom

After each fix, restart Odoo and check the log.

Why This Happens

Odoo loads modules in dependency order at every boot. Each module imports its Python files, which triggers the standard Python import machinery. The five common failure modes:

1. Missing module dependency. Your code does from odoo.addons.x import Y, but x is not in your manifest's depends. Odoo loaded your module before x, so the import fails.
2. Typo in an import path. sale_subscritpion instead of sale_subscription. Mechanical, easy to miss.
3. addons_path is wrong. The directory containing the missing module is not listed. Odoo cannot find it to load.
4. Python syntax error or runtime error at module level. Code that runs at import time (like os.environ['X'] outside a function) raises and aborts the load.
5. Circular imports. Module A imports from Module B which imports from Module A. Python deadlocks.

Cause 4 has a special variant on Odoo 18.0+ — using models.Model.__init_subclass__ hooks at module import time fails if the registry is not yet built.

Step-by-Step Diagnosis

1. Read the full traceback. Not just the last line. The chain of File "...", line N entries shows the import path. The first line in your code (not Odoo's) is where the bug is.

2. Identify the failing import. Look at the line your traceback shows. It is one of:

• from odoo.addons.X import Y — module dependency or addons_path issue.
• import some_python_lib — third-party Python dependency missing (e.g., import openpyxl).
• from .models import X — internal import of a sibling file that itself failed to import.

3. Check __manifest__.py depends.

'depends': ['sale', 'sale_management'],   # is sale_subscription here?

If the failing import is from odoo.addons.X.something, then X must be in depends.

4. Check addons_path.

sudo -u odoo /opt/odoo/odoo-bin --config /etc/odoo/odoo.conf --print-config | grep addons_path
ls /opt/odoo/enterprise/sale_subscription   # does the directory exist?

If the directory exists but is not in addons_path, add it. If the directory is missing, install or pull the module.

5. Check Python dependencies.

sudo -u odoo /opt/odoo/venv/bin/pip list | grep -i <package>

If a third-party Python package is missing, install it in Odoo's virtualenv (not system-wide).

6. Check for module-level execution. Open the failing file. Anything between from ... import ... lines and class X(...) declarations runs at import time. Errors there abort the load. Move them inside class methods or __init__ files where they belong.

Permanent Fix

For missing depends, add the module:

{
    'name': 'Sale Extension',
    'version': '17.0.1.0.0',
    'depends': [
        'sale',
        'sale_management',
        'sale_subscription',   # was missing
    ],
    'data': [...],
}

For typos, fix the import path. Use your editor's go-to-definition to verify before assuming.

For addons_path issues, edit odoo.conf:

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

Restart Odoo. Use absolute paths only — relative paths break when Odoo is run as a service.

For third-party Python deps, install in Odoo's virtualenv and add to requirements.txt:

sudo -u odoo /opt/odoo/venv/bin/pip install openpyxl
echo "openpyxl>=3.0" >> /opt/odoo/custom_addons/sale_extension/requirements.txt

Future deploys reading requirements.txt will install it automatically.

For module-level execution errors, refactor:

# WRONG — runs at import time
import requests
API_BASE = requests.head('https://example.com').headers['X-API']  # network call at import!

class SaleOrder(models.Model):
    ...

# RIGHT — defers to runtime
import requests

class SaleOrder(models.Model):
    @api.model
    def _get_api_base(self):
        return requests.head('https://example.com').headers['X-API']

For circular imports, restructure: extract the shared code into a third module both can depend on, or move the import inside the function that needs it (from odoo.addons.X import Y inside the function body).

How to Prevent It

• Lint imports in CI. pyflakes or ruff catches typo'd imports and unused imports cheaply. Wire into pre-commit.
• Test on a fresh Odoo install in CI. Install your module on a fresh database with only its declared dependencies. Catches missing depends and missing third-party libraries before merge.
• Pin Python dependencies. Every module that imports a third-party Python library must list it in requirements.txt. Without this, deploys break the first time a server is rebuilt without the implicit package.
• Module-level code is forbidden. Code review rule: nothing executes at import time except imports themselves and class declarations. All side effects go inside methods.
• Explicit addons_path in odoo.conf. No globs, no symlinks, no environment variables. One absolute path per directory. Predictable and grep-able.
• Smoke-boot after every config change. A 30-second --stop-after-init boot test in CI catches addons_path and depends issues without needing real data.

Related Errors

• Module installation error: version mismatch — sibling failure earlier in the load.
• Server vs modules version mismatch — different validator, same boot phase.
• KeyError: environments_cache after upgrade — what happens when the load succeeds but state is stale.
• Data not found during init — failure mode after Python load succeeds but data load fails.

Frequently Asked Questions

My module loads fine in dev but fails in production. Why?

Almost always one of: a third-party Python library installed in your dev shell but not in production's virtualenv; an addons directory that exists in dev's addons_path but is missing from production's; a Python version difference (production on 3.10, dev on 3.12) tripping a syntax feature. Check Python version, virtualenv contents, and addons_path side by side.

How do I install a Python dependency in Odoo's virtualenv specifically?

/opt/odoo/venv/bin/pip install <package>. Never pip install system-wide for Odoo dependencies — system Python is for system tools. Each Odoo deployment should have its own virtualenv.

Can I use a try / except ImportError to make a third-party library optional?

Yes, and this is good practice for libraries used only in optional features:

try:
    import openpyxl
    HAS_OPENPYXL = True
except ImportError:
    HAS_OPENPYXL = False

class XlsxExport(models.AbstractModel):
    def export(self):
        if not HAS_OPENPYXL:
            raise UserError(_("Install openpyxl to enable XLSX export."))
        ...

Why does Odoo load modules in this order?

Odoo computes a topological sort of the dependency graph and loads in dependency order. base loads first, then everything that depends only on base, then their dependents, and so on. Your module loads after every module in its depends. If something is missing from depends, Odoo loads in the wrong order and imports fail.

---

Need help with a tricky Odoo error? ECOSIRE's Odoo experts have shipped 215+ modules — get expert help.