Fix Python ModuleNotFoundError: No module named | Erropedia

Symptoms

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

ModuleNotFoundError: No module named 'some_module'

This error halts execution immediately. The script cannot proceed because the required module is missing or inaccessible.

Root Causes

Module not installed: The module is not present in your Python environment.
Wrong Python environment: You installed the module in a different Python interpreter or virtual environment than the one running the script.
Typo in module name: The import statement has a misspelling or incorrect case.
PYTHONPATH misconfiguration: The module's directory is not in Python's search path.
Incorrect file structure: The module is not in the expected location relative to the script.
Circular imports: Two modules depend on each other, causing import failure.

Step-by-Step Fix

Verify module name: Check the spelling and case in your import statement. For example, import numpy vs import Numpy.
Check installed modules: Run
```
pip list
```
or
```
pip freeze
```
to see if the module is installed.
Install the missing module: Use
```
pip install module_name
```
Replace module_name with the actual name (e.g., pip install requests).
Use correct Python interpreter: Ensure you are using the same Python that has the module installed. Run
```
which python
```
(Linux/macOS) or
```
where python
```
(Windows) to check. Install the module using that interpreter:
```
python -m pip install module_name
```
Activate virtual environment: If using a virtual environment, activate it first:
```
source venv/bin/activate
```
(Linux/macOS) or
```
venv\Scripts\activate
```
(Windows). Then install the module.
Add module path to sys.path: If the module is in a custom location, add the path in your script:
```
import sys
sys.path.append('/path/to/module')
import your_module
```
Check for circular imports: Restructure your code to avoid two modules importing each other directly. Use import inside functions if necessary.

Alternative Fixes

Use requirements.txt: If you have a requirements.txt file, install all dependencies at once:
```
pip install -r requirements.txt
```
Upgrade pip: Sometimes outdated pip causes installation issues:
```
pip install --upgrade pip
```

Reinstall the module: Uninstall and reinstall:

pip uninstall module_name
pip install module_name

Use conda (if applicable): For Anaconda users:
```
conda install module_name
```

Prevention

Use virtual environments: Isolate dependencies per project to avoid conflicts.
Document dependencies: Maintain a requirements.txt file for each project.
Check Python version compatibility: Some modules require specific Python versions. Verify before installing.
Use explicit imports: Avoid wildcard imports (from module import *) to reduce ambiguity.
Test in a clean environment: Run your script in a fresh virtual environment to confirm all dependencies are listed.

Additional Tips

If you are using an IDE like PyCharm or VS Code, ensure the correct Python interpreter is selected in the IDE settings. Sometimes the IDE uses a different environment than the terminal. Also, check for multiple Python installations on your system; you can list them with where python (Windows) or which -a python (Linux/macOS).