# 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.

Source: https://livops.dev/en/guides/error-module-not-found-python

By Livops team, the people who build and run Livops. Updated 19 November 2026.

What it looks like when a deployed app or bot stops on it:

```text
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:

```text
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:

```sh
.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.

```sh
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](https://livops.dev/en/docs/error-start#py-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)](https://docs.python.org/3/library/exceptions.html). Checked 19 November 2026.
2. [Python docs — Tutorial, Modules (the module search path)](https://docs.python.org/3/tutorial/modules.html). Checked 19 November 2026.
3. [Python docs — venv](https://docs.python.org/3/library/venv.html). Checked 19 November 2026.
4. [Python docs — What's New in Python 3.12](https://docs.python.org/3/whatsnew/3.12.html). Checked 19 November 2026.
5. [pip — User Guide (requirements files)](https://pip.pypa.io/en/stable/user_guide/). Checked 19 November 2026.
