Introducing Livops 2.0! Promo codeCEOgives you 8,000 so‘m on your balance.What’s new

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.py on disk, import config in 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 your Procfile, it points a bare python, gunicorn, uvicorn, celery, flask or pip in 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/python yourself.
  • 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 to requirements.txt — translated for the common cases in the table above and others, such as telebot to pyTelegramBotAPI — 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-version file 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.txt for 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

  1. Python docs — Built-in exceptions (ModuleNotFoundError) (docs.python.org). Checked .
  2. Python docs — Tutorial, Modules (the module search path) (docs.python.org). Checked .
  3. Python docs — venv (docs.python.org). Checked .
  4. Python docs — What's New in Python 3.12 (docs.python.org). Checked .
  5. 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 app

Got a question? — @livops_uz