Fix Python ModuleNotFoundError: No module named 'module'

Symptoms

When running a Python script, you encounter an error similar to:

ModuleNotFoundError: No module named 'requests'

Or more generally:

ModuleNotFoundError: No module named 'module_name'

The error stops script execution immediately. It can occur for built-in modules, third-party packages, or your own modules.

Root Causes

• Module not installed – The required third-party package is not installed in the current Python environment.
• Wrong Python environment – The module is installed in a different virtual environment or Python interpreter than the one running the script.
• Module name typo – The import statement has a spelling error or incorrect case.
• Missing __init__.py – For custom modules, the directory is not recognized as a package.
• PYTHONPATH misconfiguration – The module’s location is not in Python’s search path.
• Multiple Python versions – Pip installed the module for Python 2 but you are running Python 3, or vice versa.

Step-by-Step Fix

1. Verify the Module Name and Installation

First, check if the module is installed by running:

pip list | grep module_name

If not installed, install it:

pip install module_name

For Python 3, use pip3 if needed:

pip3 install module_name

2. Check the Python Interpreter

Ensure you are using the correct Python interpreter. Run:

which python

Or on Windows:

where python

Then check if the module is available for that interpreter:

python -c "import module_name"

3. Use a Virtual Environment

Create and activate a virtual environment to isolate dependencies:

python -m venv myenv
source myenv/bin/activate  # Linux/Mac
myenv\Scripts\activate  # Windows

Then install the module inside the environment:

pip install module_name

4. Check for Typos and Case Sensitivity

Python module names are case-sensitive. Ensure the import matches the installed package name. For example:

import numpy  # correct
import Numpy  # wrong

5. For Custom Modules: Add __init__.py

If you are importing from a local directory, ensure the directory contains an __init__.py file (can be empty) to make it a package.

6. Adjust PYTHONPATH

If your module is in a non-standard location, add it to PYTHONPATH:

export PYTHONPATH="/path/to/your/module:$PYTHONPATH"

Or in Python code:

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

Alternative Fixes

• Reinstall the module – Sometimes a corrupted installation can be fixed with pip install --force-reinstall module_name.
• Install using conda – If using Anaconda, try conda install module_name.
• Check for circular imports – In complex projects, circular imports can cause ModuleNotFoundError. Restructure your imports.
• Use pip list to see installed packages – Verify the exact name and version.

Prevention

• Always use virtual environments for project isolation.
• Use a requirements.txt file to track dependencies: pip freeze > requirements.txt.
• When sharing code, include instructions for setting up the environment.
• Regularly update pip and Python: pip install --upgrade pip.
• Use an IDE with integrated environment management (e.g., PyCharm, VS Code) to avoid interpreter confusion.
• Double-check import statements for typos and case.

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