Odoo Module Not Found / Cannot Install: Complete Fix Guide

Error Messages

# Variant 1: Module not visible in Apps
"Module 'my_module' not found in the list of available modules"

# Variant 2: Dependency error
"Unmet module dependencies: my_module depends on base_setup which is not available"

# Variant 3: Python import error
"ModuleNotFoundError: No module named 'odoo.addons.my_module'"

# Variant 4: Manifest error
"SyntaxError in __manifest__.py"

Cause 1: Module Not in addons_path

# Most common cause. Check your addons_path:
grep addons_path /etc/odoo/odoo.conf

# Verify your module is in one of those directories:
ls -la /opt/odoo/custom-addons/my_module/

# Fix: add the parent directory to addons_path:
# odoo.conf:
addons_path = /opt/odoo/odoo/addons,/opt/odoo/custom-addons

# Restart Odoo after changing addons_path
systemctl restart odoo

Cause 2: Missing __init__.py

# Every Odoo module directory AND subdirectory needs __init__.py
my_module/
├── __init__.py          ← REQUIRED
├── __manifest__.py      ← REQUIRED
├── models/
│   ├── __init__.py      ← REQUIRED
│   └── my_model.py
├── views/
│   └── my_views.xml
└── security/
    └── ir.model.access.csv

# Root __init__.py must import models:
# __init__.py:
from . import models

# models/__init__.py must import model files:
# models/__init__.py:
from . import my_model

Cause 3: Missing __manifest__.py

# Module MUST have __manifest__.py (not __openerp__.py for Odoo 10+)
# Minimum valid manifest:
{
    'name': 'My Module',
    'version': '19.0.1.0.0',
    'depends': ['base'],
    'data': [],
    'installable': True,
}

# Common manifest errors:
# - Missing comma between entries
# - Trailing comma in last entry (Python allows this, but check syntax)
# - Wrong quotes (use single quotes in Python dicts)
# - installable: False (module won't show in Apps)

Cause 4: Update Apps List Not Run

# After adding a new module, you must update the apps list:
# Method 1: UI
# Settings → Apps → Update Apps List → Update

# Method 2: Command line
python odoo-bin -d dbname -u base --stop-after-init

# Method 3: Developer mode
# Enable developer mode → Apps → Update Apps List

# NOTE: In Odoo 16+, you may need to remove the "Apps" filter
# in the Apps list to see non-app modules

Cause 5: Missing Dependencies

# If __manifest__.py depends on a module that isn't installed:
# 'depends': ['sale', 'custom_module_xyz'],
# → Odoo can't install because custom_module_xyz doesn't exist

# Fix: install all dependencies first
# Or check if the dependency name is spelled correctly
# Common typo: 'sales' instead of 'sale'

Cause 6: Python Package Missing

# If the module imports a Python library not installed:
# models/my_model.py:
import pandas  # ← Not installed in Odoo's virtualenv

# Error: ModuleNotFoundError: No module named 'pandas'

# Fix: install in the correct virtualenv
source /opt/odoo/venv/bin/activate
pip install pandas
systemctl restart odoo

Cause 7: File Permissions

# Odoo user can't read the module files:
ls -la /opt/odoo/custom-addons/my_module/

# Fix: set correct ownership
chown -R odoo:odoo /opt/odoo/custom-addons/my_module/
chmod -R 755 /opt/odoo/custom-addons/my_module/

Cause 8: Syntax Error in Python

# A Python syntax error prevents the module from loading:
# Check Odoo logs:
grep -i "syntaxerror\|importerror" /var/log/odoo/odoo.log | tail -10

# Common Python errors:
# - IndentationError (mixed tabs and spaces)
# - SyntaxError (missing colon, unmatched parentheses)
# - ImportError (wrong import path)

# Test the file manually:
python3 -c "import ast; ast.parse(open('models/my_model.py').read())"

Cause 9: XML Syntax Error in Data Files

# Invalid XML in views or data files:
# Check Odoo logs for:
# "ParseError: Invalid view definition" or
# "lxml.etree.XMLSyntaxError"

# Validate XML:
xmllint --noout views/my_views.xml

# Common XML errors:
# - Unclosed tags
# - & instead of &
# - < or > in text content (use < >)
# - Wrong attribute names

Diagnosis Checklist

1. Module directory exists in an addons_path directory?
2. Has __init__.py in root and all subdirectories?
3. Has valid __manifest__.py with installable: True?
4. Updated Apps List after adding the module?
5. All dependencies available and installed?
6. All Python packages installed in the correct virtualenv?
7. File permissions allow Odoo user to read?
8. No Python syntax errors? (check logs)
9. No XML syntax errors? (check with xmllint)
10. Removed "Apps" filter in module list? (Odoo 16+)

DeployMonkey

DeployMonkey handles module installation and dependency management. Upload your custom module via Git, and the AI agent validates the manifest, checks dependencies, and installs it correctly.