When something breaks
ModuleNotFoundError on the server: works locally, fails after deploy
In short
ModuleNotFoundError on a server almost always means the library is installed on your computer but not listed in requirements.txt, so the server never installed it. The next most common cause is that the install name differs from the import name: import PIL is installed as Pillow, import cv2 as opencv-python-headless, import telegram as python-telegram-bot. If the missing module is one of your own files, check that the file was uploaded and that the letter case matches, because a Linux server treats utils.py and Utils.py as different files. The error line in the build or run logs names the exact module that is missing.
- ModuleNotFoundError: No module named X means Python found module X neither among installed libraries nor among the project files.
- A server installs only the libraries listed in requirements.txt or in the dependencies section of pyproject.toml.
- The import name and the install name often differ: PIL is Pillow, cv2 is opencv-python, sklearn is scikit-learn, bs4 is beautifulsoup4.
- Linux file names are case sensitive, so import Utils finds utils.py on Windows and macOS but not on a server.
- A clean virtual environment is the easiest pre-flight check: if the project starts there, it will start on the server too.
Everything runs on your computer, and after deploying the logs show a single line: ModuleNotFoundError: No module named and a module name. It is one of the most common errors when moving a Python project anywhere, be it a hosting platform, a VPS or a friend's laptop. The code is usually fine. Over months of work your machine has collected libraries the project never mentions, while the server starts from scratch and installs only what is listed explicitly.
The good news is that the error always names what is missing. All that is left is to figure out which of five cases you are in: the library is not listed, it has a different install name, the Python version differs, your own file was not found, or a file of yours shadows a library. Below they are in order, from the most common to the rare ones.
| In your code | In requirements.txt | Note |
|---|---|---|
| import PIL | Pillow | The original PIL is long abandoned; Pillow replaced it |
| import cv2 | opencv-python-headless | A server has no screen, so use the build without windows and GUI parts |
| import telegram | python-telegram-bot | The package simply named telegram is unrelated to this library |
| import dotenv | python-dotenv | The package named dotenv is a different library |
| import sklearn | scikit-learn | The sklearn install name is deprecated and fails |
| import bs4 | beautifulsoup4 | The 4 in the package name is required |
| import yaml | PyYAML | There is no install name yaml |
| import jwt | PyJWT | The package named jwt is a different library with another API |
Find the missing module name in the logs#
Open the build or run logs and find the last line before the stop: ModuleNotFoundError: No module named followed by a name in quotes. The lines above usually show the file and line number with that import. Decide right away whose module it is: if the name looks like a library such as requests, aiogram or PIL, the problem is your dependencies, and if it looks like a file from your folder such as config, handlers or utils, the problem is the project structure. That tells you which of the next steps applies.
Add the library to requirements.txt#
A server installs only what is listed in requirements.txt at the project root or in the dependencies section of pyproject.toml. If you once ran pip install on your machine and never wrote the package down, it exists locally and not on the server. Open requirements.txt, add the missing package name on its own line and upload the project again. If there is no such file at all, create one with one library per line and only what your code actually imports.
Match the install name to the import name#
Many libraries are imported under one name and installed under another: import PIL is Pillow, import cv2 is opencv-python-headless, import telegram is python-telegram-bot, import dotenv is python-dotenv, import sklearn is scikit-learn, import bs4 is beautifulsoup4, import yaml is PyYAML. If requirements.txt contains the import name, either nothing gets installed or an unrelated package with a similar name does, and the error stays. When in doubt, look the library up on PyPI, where the install command is shown at the top.
Check the Python version#
Some modules exist only in certain Python versions: a few were removed from the standard library, some are new, and some packages do not ship builds for the very latest version yet. If the error is about a module you never installed yourself, such as distutils or imp, the server most likely runs a newer Python than you do. Check yours with python --version and, if you need exactly that version, put it in a .python-version file at the project root so Netrun builds the project on it. Updating the code or the library for current Python is the better long-term fix.
Make sure your own file was uploaded and named correctly#
If the missing module is one of yours, such as config or handlers, first confirm the file was uploaded at all: a .gitignore rule may have excluded it, or it may sit in another folder. Then compare the letter case: Windows and macOS treat utils.py and Utils.py as the same file, while a Linux server does not, so import Utils fails there. Finally check the path: an import like from app.utils import ... works only when the project starts from the folder that contains app. Move the entry point to the project root or fix the import path.
Make sure none of your files shadows a library#
If you name your own file after a library, for example telegram.py, requests.py or openai.py, Python finds your file first and never reaches the real library. The error then looks odd: the module seems to exist, but the name you need is not inside it, or Python complains about a partially initialized module. Rename your file to something of your own, such as my_bot.py, and delete any __pycache__ folder that ended up in the upload.
Test the project in a clean environment before deploying#
The most reliable way to catch every missing dependency at once is to repeat what the server does. Create an empty virtual environment with python -m venv, activate it, install the dependencies with pip install -r requirements.txt and run the project. Whatever is missing shows up right on your computer, and you do not have to redeploy in circles. Do not put the venv folder into the upload: the libraries are installed during the build.
ModuleNotFoundError on a server is almost always a mismatch between your computer and your dependency list, not broken code. List everything the project imports in requirements.txt, check the package names and check your own files for letter case, and that covers the vast majority of cases. On Netrun the build and run logs stream live in your dashboard, so you see the missing module name right away and upload the fixed version over the old one. Try Netrun.
Common questions
Why does it work on my computer but not on the server?
Because the library is already installed on your computer, for this project or another one. The server starts from an empty environment and installs only what requirements.txt lists. Anything you installed by hand and never wrote down simply does not exist there.
I added the package to requirements.txt and the error is still there. Why?
Most likely you wrote the import name, while the package is installed under another one: Pillow instead of PIL, or python-telegram-bot instead of telegram. Check the exact name on PyPI. Another cause is a requirements.txt that sits in a subfolder instead of the project root, so it was never picked up.
Can I just run pip freeze and use the output as requirements.txt?
You can, but it dumps your whole environment, including unrelated packages, Windows-only packages and lines with paths to folders on your machine. That often makes the build fail at the install step. It is safer to list by hand only what the code imports, or to run freeze inside a clean virtual environment for this project.
What if the missing module is my own file, not a library?
Check three things: the file was uploaded, the letter case of the file name matches the import, and the import path starts from the folder the project runs from. A Linux server is stricter about case than Windows or macOS, so Config.py and config.py are two different files there.
What is the difference between ModuleNotFoundError and ImportError?
ModuleNotFoundError is a specific kind of ImportError: the module was not found at all. A plain ImportError saying cannot import name means the module was found but the name you want is not in it, usually because of a different library version or a file of yours named after the library.
Can I run a Python project — Django, Flask or FastAPI?
Yes. Put your dependencies in requirements.txt — Netrun detects Python and builds the project for you. Django, Flask and FastAPI are supported; the app should listen on the port from the environment variable, and keys and database access are set as secrets rather than in the code.
Where can I see the logs and status of my project?
The project page shows the status, the logs and the event history — together they show what is happening with the project right now. The log view also reaches further back: scroll up and earlier lines load on their own.