Troubleshooting

ModuleNotFoundError: No module named: find the right Python, venv and package name

ModuleNotFoundError: No module named means this Python cannot find it. Fix the wrong interpreter, an inactive venv, pip vs import names and local files.

Published ~7 min read
On this page

Short answer: ModuleNotFoundError: No module named 'x' means the Python that ran your code searched its whole sys.path and found no module called x. Usually the package is installed for a different Python (another version, or outside your virtual environment), or the name you import differs from the name you install. Check which interpreter runs, then install with that interpreter:

bash · any Linux or macOS
python3 -c "import sys; print(sys.executable)"   # which Python runs your code
python3 -m pip --version                          # which Python this pip installs into
python3 -m pip install PACKAGE                    # install for exactly that Python

If the two paths differ, that is your bug. The outputs on this page come from Python 3.11.2 on Debian 12, run with python3 -c and throwaway files in a scratch folder (long paths shortened to /srv/demo); nothing was installed from the internet.

Installed, but for another Python

Every Python interpreter has its own site-packages. A package installed for /usr/bin/python3 does not exist for a virtual environment, for python3.12 next to it, or for a pyenv or conda Python. Here PyYAML is installed system-wide from Debian’s python3-yaml package, and a fresh virtual environment cannot see it:

output · Debian 12, Python 3.11.2
$ python3 -c "import yaml; print(yaml.__file__)"
/usr/lib/python3/dist-packages/yaml/__init__.py
$ python3 -m venv --without-pip .venv
$ .venv/bin/python -c "import yaml"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
ModuleNotFoundError: No module named 'yaml'

The same happens with a pip command that belongs to another interpreter. pip install requests may run the pip of one Python while python starts another. The pip documentation recommends python -m pip for this reason: it runs pip with the interpreter you named, so /usr/bin/python3.11 -m pip installs for exactly that Python. python3 -m pip --version prints where it installs:

output · Debian 12
$ python3 -m pip --version
pip 23.0.1 from /usr/lib/python3/dist-packages/pip (python 3.11)
  • Script with a shebang: #!/usr/bin/env python3 takes the first python3 on PATH, #!/usr/bin/python3 always the system one. Run head -1 script.py and compare with sys.executable.
  • Editor or IDE: the interpreter selected in the editor can differ from your terminal’s. Print sys.executable from inside the program to be sure.
  • Jupyter: a notebook runs in its kernel’s Python, not the one your shell sees. Run import sys; print(sys.executable) in a cell and install with that path plus -m pip.

The package is really not installed

If python3 -m pip show PACKAGE prints nothing, install it into the environment your code runs in. On Debian 12 and later and Ubuntu 23.04 and later, installing into the system Python with pip is refused with error: externally-managed-environment, so use a virtual environment or the distribution package:

Debian · Ubuntu
python3 -m venv .venv && . .venv/bin/activate
python -m pip install pyyaml            # inside the venv
# or, for the system Python, the distribution package:
sudo apt install python3-yaml

If python3 -m venv or -m pip fails because pip itself is missing, that is covered in pip: command not found and how to install pip. And if the shell cannot find python at all, see python: command not found.

The virtual environment is not active

Activation only changes the current shell: it puts .venv/bin first on PATH. A new terminal, a second SSH session, a Makefile or a deploy script starts without it, and python3 is the system one again, which does not have your packages. Two ways to be independent of activation:

bash
# call the venv's interpreter by its path; no activation needed
/srv/demo/.venv/bin/python app.py
# or check what an activated shell really runs
command -v python    # should print /srv/demo/.venv/bin/python

In a script that runs under sh, source .venv/bin/activate fails before anything is imported; that case is in source: not found.

The import name is not the package name

pip install takes the name of the distribution on PyPI; import takes the name of the module inside it, and the two often differ. Installing the import name either fails or installs something else. The common pairs, with the Debian package for the system Python (names as in Debian 12):

importpip installDebian, Ubuntu
PILpillowpython3-pil
cv2opencv-pythonpython3-opencv
yamlpyyamlpython3-yaml
sklearnscikit-learnpython3-sklearn
bs4beautifulsoup4python3-bs4
dotenvpython-dotenvpython3-dotenv

Two of these bite often. The PyPI project sklearn is a deprecated placeholder whose page says to use pip install scikit-learn rather than pip install sklearn. And the opencv-python project explains that the import name stayed cv2 to stay consistent with the many existing tutorials. When you do not know the package for an import, the project’s own documentation or its PyPI page shows the import line in its first example.

It works in your shell but not under sudo, cron or systemd

These start your program with another environment, and often another Python:

  • sudo replaces PATH with secure_path from /etc/sudoers (set by default on Debian and Ubuntu), so sudo python3 is the system Python even inside an activated venv. Packages installed with pip install --user live in your home directory and are not on root’s path either.
  • cron runs jobs with /bin/sh and a minimal environment, without your shell startup files, so no venv, pyenv or conda is active.
  • systemd runs the ExecStart= command directly: per systemd.service(5) it is not passed through a shell, and no login shell startup files are read.

The fix for all three is the same: name the interpreter by its full path.

sudo · crontab · systemd unit
sudo /srv/demo/.venv/bin/python app.py
*/5 * * * * cd /srv/demo && /srv/demo/.venv/bin/python app.py >> /srv/demo/cron.log 2>&1
ExecStart=/srv/demo/.venv/bin/python /srv/demo/app.py

On a VPS or dedicated server that hosts several apps, give each one its own virtual environment and point its service file at that venv’s python. Then a system upgrade or another app’s packages cannot take a module away from it.

A local file hides the real module

Python puts a directory in front of everything else on sys.path: the script’s directory for python script.py, the current directory for python -m, python -c and the interactive prompt. A file in that directory with the same name as a package wins. If you need a submodule, the error then looks like a missing module:

output · a file named email.py in the current folder
$ touch email.py
$ python3 -c "import email.mime"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
ModuleNotFoundError: No module named 'email.mime'; 'email' is not a package

The suffix 'email' is not a package is the giveaway. A script you named after the library you use produces the related circular import messages instead. Here a script called yaml.py imports itself instead of PyYAML:

output · a script named yaml.py, last lines of each traceback
$ python3 yaml.py
AttributeError: partially initialized module 'yaml' has no attribute 'safe_load' (most likely due to a circular import)
$ python3 yaml.py      # with: from yaml import safe_load
ImportError: cannot import name 'safe_load' from partially initialized module 'yaml' (most likely due to a circular import) (/srv/demo/yaml.py)

Rename the file and delete the __pycache__ folder next to it. Python 3.13 and later add a hint to the AttributeError case that suggests renaming the file. Since 3.11, python3 -P (or PYTHONSAFEPATH=1) leaves that first directory off sys.path; with it, the email.py example above imports the real module.

No module named your own package

The same rule explains No module named 'app' for code in your own project. Running a file inside a package puts that file’s folder first on sys.path, not the project root, so the package itself is not importable. Run it as a module from the project root instead:

output · project with app/__init__.py, app/utils.py, app/main.py
$ python3 app/main.py
Traceback (most recent call last):
  File "/srv/demo/proj/app/main.py", line 1, in <module>
    from app import utils
ModuleNotFoundError: No module named 'app'
$ python3 -m app.main
ok 1

Setting PYTHONPATH to the project root also works, see environment variables on Linux, but python -m is the cleaner habit.

Frequently asked

Why do I get No module named after pip install?

pip installed the package for a different Python than the one running your code. Compare python3 -c "import sys; print(sys.executable)" with python3 -m pip --version, then install with the interpreter that runs your code, for example /path/to/.venv/bin/python -m pip install NAME. A virtual environment that is not active is the most common case.

Why is it pip install pillow but import PIL?

pip installs a distribution by its PyPI name, while import uses the module name inside it, and the two can differ. Other common pairs are opencv-python for cv2, pyyaml for yaml, scikit-learn for sklearn, beautifulsoup4 for bs4 and python-dotenv for dotenv. The PyPI project called sklearn is a deprecated placeholder that tells you to install scikit-learn.

Why does my script work in the terminal but not with sudo or cron?

sudo replaces PATH with secure_path from /etc/sudoers (set by default on Debian and Ubuntu), and cron runs jobs with /bin/sh and a minimal environment, so neither sees your activated virtual environment, pyenv or conda. They run a different python3 without your packages. Call the venv interpreter by its full path, such as /srv/app/.venv/bin/python app.py.

What does No module named 'x.y'; 'x' is not a package mean?

Python found a plain file named x.py, usually in your script's folder or the current directory, before the real package x. Because sys.path starts with that folder, your file hides the library. Rename the file, delete the __pycache__ folder next to it and run again.

Related articles

All troubleshooting