Python ModuleNotFoundError — Wrong Interpreter or Missing Dependency

Diagnose ModuleNotFoundError by confirming which interpreter runs the code, which environment holds the package, and whether the import name differs from the package name.

beginnerdebuggingpythondependenciesvirtualenv

Symptoms

ModuleNotFoundError: No module named 'requests' even though pip install succeeded
The code runs in the IDE but fails in the terminal, CI, or a cron job
A dependency is listed in requirements.txt but the import still fails

Possible causes

The code runs under a different Python interpreter or virtual environment than the one where the package was installed
The dependency was never installed, or installation failed silently
The distribution name differs from the import name, such as beautifulsoup4 versus bs4
The working directory or PYTHONPATH changes which local package shadows the intended module

Diagnosis steps

Print the interpreter and module search path used by the failing process

python -c "import sys; print(sys.executable); print('\n'.join(sys.path))"

Interpretation

Compare the executable with the one used for pip install. A system Python and a virtualenv Python have different site-packages.

Confirm whether the package is visible to that interpreter

python -m pip show requests

Interpretation

If pip show reports the package but import fails, you may be using a different interpreter or an import-name mismatch.

Reproduce the import directly

python -c "import requests; print(requests.__version__)"

Interpretation

This isolates environment problems from application code. If it fails, fix the environment before debugging the app.

Root cause

The failing interpreter cannot find the module on its sys.path. This is usually a virtualenv mismatch, a missing installation, a package/import name mismatch, or a local file shadowing the package.

Fix

Create and activate a virtual environment, install dependencies with the same interpreter using python -m pip install -r requirements.txt, and run code with that interpreter. In CI, pin the Python version and install before running tests. Check the import name in the package documentation.

Risk note

Avoid installing packages globally or with sudo to make an error disappear. Do not add arbitrary directories to PYTHONPATH; fix environment isolation instead.

Verify the fix

Run the import and the application under the same interpreter. Confirm pip show and python -c import point to the same environment, then run the test suite in a clean virtualenv and in CI.

The interpreter is part of the bug

pip install requests installs into one environment. If the program runs under another Python, the package is invisible. IDEs often select a virtualenv automatically, while a terminal may use the system interpreter.

which python
python -c "import sys; print(sys.executable)"
python -m pip show requests
python -c "import requests; print(requests.__version__)"

Always use python -m pip so pip runs inside the same interpreter that will run the code.

Fix

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install -r requirements.txt
python -m pytest

For CI, declare the Python version and install dependencies in the same job and environment that runs tests. For package/import mismatches, check the official documentation; beautifulsoup4 imports as bs4, and python-dateutil imports as dateutil.

Verify

sys.executable points to the intended environment.
pip show <package> and python -c "import <module>" use the same interpreter.
A clean virtualenv install followed by the test suite passes.
The same command works in CI and locally.

Shadowing

A local file named requests.py or a directory named after a dependency can shadow the installed package. Check sys.path order and rename the local file. Removing the package from sys.modules does not fix shadowing; the import path does.