Fixing ModuleNotFoundError in Python, One Cause at a Time

ModuleNotFoundError has only a handful of causes, and they're easy to tell apart if you check them in the right order. The mistake is guessing: installing the package again, renaming files, copying folders around. Each guess can add a new problem on top of the old one.

Read the name in the error first

import requestz

Traceback (most recent call last):
  File "/home/you/project/app.py", line 1, in <module>
    import requestz
ModuleNotFoundError: No module named 'requestz'

The last line names the module Python looked for and couldn't find. Read it slowly before doing anything. A surprising number of these are spelling: requestz, Pandas with a capital P, bs4 vs beautifulsoup4. Module names are case-sensitive.

Cause 1: the package is installed in a different Python

This is the most common one by far. You ran pip install requests, it said "Successfully installed", and the import still fails. That means pip installed into one Python and your script runs with another. Maybe you have two versions installed, maybe your editor uses a virtual environment and your terminal doesn't, or the other way around.

Ask the Python that fails where it is:

import sys

print(sys.executable)

Then install with that exact Python:

/path/printed/above -m pip install requests

From now on, prefer python -m pip install ... over plain pip install .... python -m pip uses the pip that belongs to the python you just typed. Plain pip can belong to a different Python on PATH, and then you're installing into the wrong place without knowing it.

Cause 2: the virtual environment isn't active

Same cause as above, more specific. You created .venv, installed packages into it, opened a new terminal tomorrow, and forgot to activate it. Your prompt usually shows (.venv) at the start when it's active. No (.venv), no packages.

In VS Code, also check the interpreter in the bottom-right corner (or "Python: Select Interpreter"). The Run button uses that one, not what your terminal uses.

Cause 3: your own module, run from the wrong folder

Here's a small project:

shop/
    main.py
    helpers/
        __init__.py
        prices.py

main.py contains from helpers.prices import add_vat. Python looks for imports starting in the folder of the script you ran, plus the installed packages. Run it from inside the project, and it works:

cd shop
python main.py

112.0

Now someone puts a test script inside the helpers folder and runs it:

from helpers.prices import add_vat

print(add_vat(50))

python helpers/try_it.py

Traceback (most recent call last):
  File "/home/you/project/shop/helpers/try_it.py", line 1, in <module>
    from helpers.prices import add_vat
ModuleNotFoundError: No module named 'helpers'

Python started looking in shop/helpers/, the script's own folder. There's no helpers folder inside helpers, so it fails. The fix is to run it as a module from the project folder, with -m and dots instead of slashes:

python -m helpers.try_it

56.0

With -m, Python starts looking in the current folder, which is shop/, so helpers is found.

Cause 4: a file of yours has the same name as a module

If you name your own file random.py, csv.py, requests.py or email.py, then import random in that folder imports your file, not Python's. You get strange errors like AttributeError: module 'random' has no attribute 'randint', or ModuleNotFoundError for something inside the real package. Rename your file, and delete the __pycache__ folder next to it.

Don't fix it with sys.path

You'll find advice to add sys.path.append("..") at the top of the file. It works on your computer, from the folder you tested in. It breaks when someone runs it from a different folder, because ".." depends on where you are, not where the file is. Fix the cause instead: the right Python, the right folder, or -m.

The checklist

1. Read the module name in the error. Spelling and case.
2. Is the install name different from the import name?
3. Print sys.executable. Install with that Python using -m pip.
4. Is the virtual environment active, in the terminal and the editor?
5. Your own module: are you running from the project folder? Try python -m.
6. Does a file of yours shadow the module's name?

What happens if you keep guessing

You install the package three more times, into three Pythons that aren't the one running your code. Now you have three copies, and the next error will be even harder to trace. Five minutes of checking beats an hour of reinstalling.

If pip install says "Requirement already satisfied" and the import still fails, what does that tell you about which Python pip is using?