Guides / ModuleNotFoundError after deploy: works locally, fails in production

Peter van Doorn Django Cloud · Checked against Django 4.2 and newer, October 2026

ModuleNotFoundError after deploy: works locally, fails in production

The app runs on your machine and crashes after deploying with ModuleNotFoundError: No module named 'something'. Your server's environment isn't the same as yours. Work out what differs: a package that was never recorded, a different Python, a case-sensitive filename, or a folder that did not ship.

What it means

Python can't import a name the code asks for. Locally it can, because your virtualenv contains years of packages you installed by hand. A server only has what you told it to install and what you uploaded.

Why it happens

1. The package isn't in requirements.txt. You ran pip install once and forgot to record it.
2. It's only in a dev file. It is in requirements-dev.txt, or a dev dependency group, and production installs without it.
3. The lock file is stale. You changed pyproject.toml but not uv.lock / poetry.lock, or requirements.txt was generated before the last pip install.
4. Different Python version. A dependency needs a newer Python than the server has, or the environment on the server is a different one from the one that runs the app.
5. Filename case. from .Models import X works on macOS (case-insensitive) and fails on Linux.
6. A local folder did not ship. It's in .gitignore or .dockerignore, or it's a package missing an __init__.py that your setup relies on.
7. Import name differs from the package name. pip install pillow gives import PIL; python-dotenv gives dotenv.

The fix

Reproduce the server's environment on your machine, in a clean virtualenv, from the same files the server uses:

python -m venv /tmp/clean
/tmp/clean/bin/pip install -r requirements.txt
/tmp/clean/bin/python manage.py check

The first import error you see is the one production sees. Add the missing package, then regenerate the pinned file from your working environment:

pip freeze > requirements.txt          # or: pip-compile requirements.in
# with uv:
uv add the-missing-package && uv lock

Check that packages are consistent with each other, and compare Python versions:

pip check
python --version    # locally, and on the server

For case problems, search for imports whose casing doesn't match the file: on Linux, python -c "import myapp.models" from the project root fails exactly like production will.

Making it stick in production

• Install from a lock file with exact versions, and use the same command in CI and in the deploy (uv sync --frozen, or pip install -r requirements.txt).
• Pin the Python version (.python-version, the Docker base image tag, or requires-python) so local and production match.
• Test on Linux in CI with a fresh environment, and run python manage.py check --deploy and the test suite there.
• Import errors for database drivers are their own case: No module named 'psycopg2'. Errors importing your settings: settings module not found.

Or skip it

Django Cloud installs your dependencies in a clean container on every build, from requirements.txt or pyproject.toml and uv.lock, on Python 3.10 to 3.13, so a missing package fails the build and not your live site.

pip install djangocloud-cli
djangocloud deploy

Get startedSee pricing

Free plans are available for students, AWS Activate startups, open-source, non-profit and research projects. See how Django Cloud compares with other ways to host Django.

Django is a registered trademark of the Django Software Foundation. Django Cloud is not affiliated with or endorsed by it. Found a mistake in this guide? Tell us and we will fix it.