Fix Python ModuleNotFoundError: No module named X

Symptoms

You run a Python script and see an error like:

ModuleNotFoundError: No module named 'requests'

This halts execution immediately. The error may occur for built-in modules, third-party packages, or your own local modules.

Root Causes

1. Module not installed – The package is missing from the current Python environment.
2. Wrong Python interpreter – You installed the module for a different Python version or virtual environment.
3. PYTHONPATH misconfiguration – Python cannot find the module’s location.
4. Circular imports or naming conflicts – Your script shares a name with a standard library module (e.g., math.py).
5. Incomplete installation – The package failed to install properly.

Step-by-Step Fix

1. Verify the module name and spelling

Check for typos. Module names are case-sensitive. For example, import numpy works, but import Numpy does not.

2. Install the missing module

Use pip to install the package. Open a terminal (or command prompt) and run:

pip install requests

If you are using Python 3 specifically, use pip3:

pip3 install requests

3. Check your Python environment

Ensure you are using the same Python interpreter where the module was installed. Run:

which python   # macOS/Linux
where python   # Windows

Then check installed packages:

pip list

If the module is not listed, you are likely in a different environment.

4. Activate the correct virtual environment

If you use virtual environments, activate it before running your script:

source venv/bin/activate   # macOS/Linux
venv\Scripts\activate      # Windows

Then install the package inside the environment.

5. Update PYTHONPATH (for local modules)

If the module is a local file, add its directory to sys.path at the top of your script:

import sys
sys.path.append('/path/to/your/module')
import your_module

Alternatively, set the PYTHONPATH environment variable.

6. Reinstall the module

Sometimes a partial installation causes the error. Reinstall with:

pip uninstall requests
pip install requests

Alternative Fixes

• Use a requirements file – Run pip install -r requirements.txt to install all dependencies at once.
• Install for the user only – Add --user flag: pip install --user requests.
• Use conda – If you use Anaconda, try conda install requests.
• Check for naming conflicts – Rename your script if it matches a standard library module (e.g., rename math.py to my_math.py).

Prevention

1. Always use virtual environments for project isolation.
2. Maintain a requirements.txt file with exact versions.
3. Run pip freeze > requirements.txt after installing packages.
4. Use an IDE that shows the active Python interpreter.
5. Test imports in a fresh environment before deploying.

By following these steps, you can quickly resolve the ModuleNotFoundError and prevent it from recurring.