Fix ModuleNotFoundError in Python
Error Reference
ModuleNotFoundError: No module named ...
Python can't find the module you're importing. Here's how to fix it fast.
Checklist
- Typos? Module names are case-sensitive —
import Pandasfails even with pandas installed. - Installed? Run
pip show PACKAGE; if it prints nothing, runpip install PACKAGE. - Virtual environment active?
which pythonshould point to the right interpreter. - Local package? Add a
__init__.pyor updatePYTHONPATH. - Different install name? Some packages install under one name but import under another (see the table below).
import pandas # ModuleNotFoundError: No module named 'pandas'
Fix: pip install pandas inside the active environment. If that "doesn't work", the sections below explain why.
Environments
The number one cause of "installed it, still not found": pip installed the package into one interpreter, and your script runs under a different one. Compare the two directly.
Which interpreter is actually running your code:
import sys
print(sys.executable)
# /home/you/projects/app/.venv/bin/python
Where pip installed the package:
pip show pandas
# Name: pandas
# Location: /usr/lib/python3/dist-packages
If the Location doesn't belong to the interpreter in sys.executable, you've found the mismatch — activate the right environment, or install into the interpreter you're actually using.
The reliable way to do that is python -m pip instead of bare pip:
python -m pip install pandas
Bare pip is whichever pip happens to be first on your PATH — it can belong to a completely different Python. python -m pip runs pip as a module of that exact interpreter, so the package lands where import will look for it.
Name shadowing
A local file with the same name as a module silently wins over the real one. Create random.py in your project and the standard library's random becomes unreachable:
# your project contains a file named random.py
import random
print(random.choice([1, 2, 3]))
# AttributeError: module 'random' has no attribute 'choice'
The same trap breaks third-party imports: a local requests.py shadows the installed requests package, and its submodule imports fail with ModuleNotFoundError. Diagnose it by checking where the module was loaded from:
import random
print(random.__file__)
# /home/you/projects/app/random.py <- shadowing!
# /usr/lib/python3.12/random.py <- correct
Fix: rename your file (and delete any stale random.pyc / __pycache__ next to it).
Install name vs import name
Some packages are installed under one name and imported under another. pip install PIL fails or installs the wrong thing — the package is called pillow:
pip install … | … then import |
|---|---|
pillow | PIL |
beautifulsoup4 | bs4 |
opencv-python | cv2 |
scikit-learn | sklearn |
pyyaml | yaml |
python-dateutil | dateutil |
When an import fails right after an apparently successful install, check the package's docs (or its PyPI page) for the actual import name.
Frequently Asked Questions
I installed the package with pip, why is it still not found?
Almost always an environment mismatch: pip installed into one Python, your code runs under another. Print sys.executable in the failing script, run pip show PACKAGE, and compare the paths. Installing with python -m pip install PACKAGE guarantees the package goes into the interpreter that runs your code.
import sys
print(sys.executable) # the interpreter that is missing the package
Why does the import work in the terminal but fail in Jupyter?
The Jupyter kernel is its own Python environment, and it is often not the one your terminal uses. Print sys.executable inside a notebook cell to see which interpreter the kernel runs. You can install straight into it from a cell with %pip, which targets the kernel environment automatically.
import sys
print(sys.executable)
# then, in its own cell:
%pip install pandas
What is the difference between ModuleNotFoundError and ImportError?
ModuleNotFoundError is a subclass of ImportError. You get ModuleNotFoundError when Python cannot locate the module at all, and a plain ImportError when the module was found but importing a specific name from it failed — for example from math import cubes. An except ImportError block catches both.