Odoo 'ImportError: No module named' — Python Import Failures Fix

ImportError in Odoo Startup

When Odoo fails to start with Python import errors, you see messages like:

ImportError: No module named 'num2words'
ModuleNotFoundError: No module named 'phonenumbers'
ImportError: cannot import name 'etree' from 'lxml'
ImportError: No module named 'xlrd'

These errors mean a Python package that Odoo or one of its modules requires is not installed in the active Python environment.

Common Missing Packages

Step 1: Verify the Correct Python Environment

The most common cause is installing the package in the wrong Python environment:

# Check which Python Odoo uses
systemctl cat odoo | grep ExecStart
# Example output: ExecStart=/opt/odoo/venv/bin/python /opt/odoo/odoo/odoo-bin ...

# Activate the SAME environment
source /opt/odoo/venv/bin/activate

# Verify the package is missing
python -c "import num2words"  # Should show ImportError

# Install in the correct environment
pip install num2words

# Verify it works now
python -c "import num2words; print('OK')"

Step 2: Install All Requirements

Odoo ships a requirements.txt that lists all dependencies:

# Activate Odoo's virtual environment
source /opt/odoo/venv/bin/activate

# Install all requirements
pip install -r /opt/odoo/odoo/requirements.txt

# Some packages need system libraries first:
sudo apt install libldap2-dev libsasl2-dev  # for python-ldap
sudo apt install libxml2-dev libxslt1-dev   # for lxml
sudo apt install libjpeg-dev zlib1g-dev     # for Pillow

Step 3: Custom Module Dependencies

Custom modules may require additional Python packages not in Odoo's requirements.txt. Check the module's manifest:

# Look for external_dependencies in __manifest__.py
'external_dependencies': {
    'python': ['boto3', 'paramiko', 'redis'],
}

# Install those packages
pip install boto3 paramiko redis

If a module fails to install with 'Python library not installed', this is the reason. Odoo checks external_dependencies before allowing module installation.

Step 4: ImportError After Upgrade

After upgrading Odoo, some packages may need updating:

# Upgrade all packages to match new requirements
source /opt/odoo/venv/bin/activate
pip install --upgrade -r /opt/odoo/odoo/requirements.txt

# Or recreate the venv from scratch
deactivate
rm -rf /opt/odoo/venv
python3.12 -m venv /opt/odoo/venv
source /opt/odoo/venv/bin/activate
pip install -r /opt/odoo/odoo/requirements.txt

Step 5: Docker-Specific Import Errors

# In Dockerfile, install packages before switching to odoo user
FROM odoo:19
USER root
RUN pip3 install num2words phonenumbers xlrd qrcode
USER odoo

# Or in docker-compose.yml with entrypoint
entrypoint: ["sh", "-c", "pip3 install num2words && exec /entrypoint.sh odoo"]

# Better: use a requirements file
COPY extra-requirements.txt /tmp/
RUN pip3 install -r /tmp/extra-requirements.txt

Step 6: C Extension Build Failures

Some packages (lxml, psycopg2, Pillow) compile C code and may fail:

# Error: lxml failed to build
# Fix: install build dependencies
sudo apt install build-essential python3-dev
sudo apt install libxml2-dev libxslt1-dev  # for lxml
sudo apt install libpq-dev                 # for psycopg2
sudo apt install libjpeg-dev libfreetype6-dev  # for Pillow

# Then retry
pip install lxml psycopg2 Pillow

Prevention

DeployMonkey pre-installs all required Python packages during instance provisioning. Custom module dependencies are detected from manifests and installed automatically. The AI agent validates imports before deploying any module.