What's happening
Python can't find a module at import time. Simple as that. But the reason varies: the package was never installed, it landed in the wrong Python environment, your pip and python binaries point to different places, or the PyPI package name differs from what you type in import.
Nail down the cause first — installing blindly wastes time and often doesn't fix anything.
Debug first
Find out exactly which Python binary is running your script:
which python
which python3
python --version
python3 --version
Then check whether the package is already installed for that specific Python:
python -m pip list | grep requests # swap 'requests' for your module name
Package shows up in the list but the error persists? That's a pip/Python mismatch — jump straight to Solution 3.
Solution 1: Install the missing package
Nine times out of ten, the package just isn't there. Install it:
pip install xxx
On machines with Python 2 and 3 coexisting, be explicit:
pip3 install xxx
# Or tie it directly to the Python binary you're using:
python -m pip install xxx
python3 -m pip install xxx
python -m pip is the safer habit. It bypasses shell PATH confusion by calling the pip that belongs to that exact Python binary.
Solution 2: Wrong virtual environment
You installed it — just into the wrong env. This catches everyone at least once.
# Is any virtualenv currently active?
echo $VIRTUAL_ENV
# Activate the right one, then install
source venv/bin/activate # Linux/macOS
.\venv\Scripts\activate # Windows
pip install xxx
Conda users:
conda activate myenv
pip install xxx
# or, if it's in the conda registry:
conda install xxx
The tell-tale sign: the package installs without errors, but the ModuleNotFoundError keeps coming back every time you open a new terminal.
Solution 3: pip/Python binary mismatch
On many Linux distros, bare pip still points to Python 2.7. You install a package, Python 3 can't see it, head-scratching ensues.
python -m pip install xxx
Once installed, confirm it landed where Python actually searches:
python -c "import xxx; print(xxx.__file__)"
The path printed should sit inside your active virtualenv or the Python 3.x site-packages directory — not somewhere under /usr/lib/python2.7/.
Solution 4: pip name vs import name mismatch
PyPI names and import names don't always match. A successful pip install doesn't guarantee you typed the right thing in import. The classic offenders:
pip install Pillow→import PILpip install scikit-learn→import sklearnpip install python-dateutil→import dateutilpip install opencv-python→import cv2pip install beautifulsoup4→import bs4
When in doubt, check the package's PyPI page or its README. The import name is always documented there.
Solution 5: Local module not on sys.path
For your own modules (not pip packages), Python simply might not know where to look:
import sys
print(sys.path) # lists every directory Python searches
Quick workaround:
import sys
sys.path.insert(0, '/absolute/path/to/your/project')
import xxx
Cleaner long-term solution: run Python from the project root, or install the package in editable mode so it's always importable:
pip install -e .
Solution 6: Python version incompatibility
Packages like tensorflow 2.x dropped Python 3.7 support. If pip install itself throws an error, read it — it usually spells out the required Python version range.
Pin an older release that still supports your Python:
pip install "somepackage==1.2.3" # last version that supported your Python
Verify the fix
# Does the import succeed?
python -c "import xxx; print('OK')"
# Where did it land?
python -c "import xxx; print(xxx.__file__)"
# What version got installed?
python -m pip show xxx
Lessons learned
- Make
python -m pip installyour default. Barepipis a trap on multi-Python systems. - Activate your virtualenv before starting work. A forgotten activation is the root cause of at least half of all "but I already installed it!" complaints.
- Commit a
requirements.txt. Runningpip install -r requirements.txtin a fresh env should reproduce the exact setup — no surprises. - When juggling Python 3.10 and 3.11 side by side, be explicit:
python3.11 -m pip install xxxremoves all ambiguity.