ModuleNotFoundError: No module named — after a deploy
Python searched sys.path and could not find the module you import. After a deploy that almost always means the package is not in requirements.txt, is listed under a different name than the one you import, or the start command runs a Python that the packages were not installed into.
By Livops team, the people who build and run LivopsUpdated
What it looks like when a deployed app or bot stops on it:
Traceback (most recent call last):
File "/app/bot.py", line 3, in <module>
from aiogram import Bot, Dispatcher
ModuleNotFoundError: No module named 'aiogram'
This page explains what Python is telling you, lists the causes from the most common, shows how to reproduce the server’s environment on your machine, and says what Livops does when an app stops this way.
What does the error mean?
ModuleNotFoundError is the subclass of ImportError that import raises when a module could not be located[1]. Python looks for a module in the folders listed in sys.path, which starts as the directory of the script you ran, then PYTHONPATH, then the installation’s site-packages[2]. If the name is in none of them, you get this error.
So the question is always the same: which environment did the server install packages into, and is the module there?
Causes, most common first
1. The package is not in requirements.txt
You installed it with pip install while writing the code and never wrote it down. The server installs only what the file lists. Add it:
aiogram>=3.4
pip freeze writes out everything installed[5]; run it inside a clean virtual environment, or it will also list every unrelated package on your machine.
2. The import name is not the package name
The name after import is not always the name on PyPI:
| You import | Put in requirements.txt |
|---|---|
PIL |
Pillow |
cv2 |
opencv-python-headless |
yaml |
PyYAML |
dotenv |
python-dotenv |
telegram |
python-telegram-bot |
bs4 |
beautifulsoup4 |
sklearn |
scikit-learn |
jwt |
PyJWT |
3. The app runs with a different Python
The packages went into a virtual environment, but the start command runs the system python or a gunicorn that lives outside it. Start the app with the environment’s own interpreter:
.venv/bin/python bot.py
.venv/bin/python -m gunicorn app:app
Do not commit .venv to make this work: a virtual environment is not movable or copyable, only recreated where it runs[3].
4. The module is your own folder
No module named 'config' or 'app' is about your code, not PyPI:
- the folder is not in the repository — check
git ls-files config/and.gitignore; - the case differs:
Config.pyon disk,import configin code; Linux does not match them; - the app is started from another directory, so the folder is not next to the script Python put on
sys.path. Start from the project root, and run a package as a module:python -m mybot.
5. It is in a development-only file
The package is in requirements-dev.txt, or you rely on an extra (uvicorn[standard]) that the production file lists without it. Move it into the file the server installs.
6. The Python version changed
Python 3.12 removed distutils, imp, asynchat and asyncore from the standard library[4]; an old package that imports them fails on a newer Python. Update the package, install setuptools (which still provides distutils)[4], or pin the Python version the code was written for.
How to confirm the fix locally
Recreate what the server does: a new virtual environment with only requirements.txt in it.
python3 -m venv /tmp/check
/tmp/check/bin/pip install -r requirements.txt
/tmp/check/bin/python -c "import aiogram"
/tmp/check/bin/python bot.py
If the import line passes and the app starts, the server will find the module too. For your own folders, git status --ignored lists what Git is leaving out.
On Livops
- One environment, used by the start command. Livops installs the dependencies into the project’s own
.venv, and when it takes the start command from yourProcfile, it points a barepython,gunicorn,uvicorn,celery,flaskorpipin it at.venv/bin. The commands it writes itself already start with.venv/bin/. If you type a start command in Settings → Start, write.venv/bin/pythonyourself. - A Tip that names the package. When the app stops on
No module named 'X', the log carries a Tip: line: if it is a library, which package to add torequirements.txt— translated for the common cases in the table above and others, such astelebottopyTelegramBotAPI— and if it is a folder of your own, to check it is committed with its files. - A failed start does not take a site down. The deploy fails as
start_failed, and a web app’s previous version keeps running. A bot’s previous version was stopped before the new one started, so the bot is down until a deploy succeeds. - Python version. Livops runs Python 3.10 to 3.14; put the version in a
.python-versionfile at the project root. - The assistant explains. The button next to a failed deploy reads the log and says what to change. It does not edit
requirements.txtfor you; you commit the fix and deploy again.
The same case is in the docs: Python could not find a module.
Questions
Why does it work on my computer and not on the server?
Your computer has the package installed, globally or in a virtual environment, and the server installs only what requirements.txt lists. Install from requirements.txt into a fresh virtual environment and you will see the same error locally.
The package is in requirements.txt. Why is it still missing?
Either the name you import is not the name pip installs (import PIL comes from Pillow), or the app runs with a different Python than the one the packages went into. Check the start command runs the virtual environment's python.
Should I commit my .venv folder?
No. A virtual environment is not movable or copyable; it is meant to be recreated where it runs. Commit requirements.txt and let the server build its own.
The missing module is my own folder. What now?
Check that the folder is committed with its files and not dropped by .gitignore, that the case of the name matches, and that the app starts from the project root so the folder is on sys.path.
Does Livops tell me which package to add?
Yes, for this error the log carries a Tip line naming the package to put in requirements.txt, including the common cases where it differs from the import name, such as cv2 and opencv-python-headless.
Sources
- Python docs — Built-in exceptions (ModuleNotFoundError) (docs.python.org). Checked .
- Python docs — Tutorial, Modules (the module search path) (docs.python.org). Checked .
- Python docs — venv (docs.python.org). Checked .
- Python docs — What's New in Python 3.12 (docs.python.org). Checked .
- pip — User Guide (requirements files) (pip.pypa.io). Checked .
Put your project online today
Connect GitHub or drop a folder. No card is asked for.
Deploy your Python appRelated
- Gunicorn "Worker failed to boot": what it means and how to fix itGunicorn's worker could not load your application, so the master process shut down. The cause is the Python traceback printed just above the message: most often a missing package or variable, or a wrong module:variable path in the gunicorn command. Fix what the traceback names and the workers boot.
- DisallowedHost: Invalid HTTP_HOST header — Django's 400 Bad RequestDjango received a request for a host name that is not in ALLOWED_HOSTS, so it answered 400 Bad Request. Add the domain the site is served on to ALLOWED_HOSTS, without https:// and without a port, or read the list from an environment variable, and redeploy.
- Conflict: terminated by other getUpdates request — how to fix itTelegram is telling your bot that another process called getUpdates with the same token and took the connection over. Two copies of the bot are polling at once: stop the other one (usually the copy still running on your computer or an old server), or get a new token from @BotFather, and the error stops.