How to Resolve "ModuleNotFoundError: No Module Named ..." in Python

The ModuleNotFoundError: No module named '...' is one of the most frequently encountered errors in Python. It occurs when Python's import system cannot locate the module you are trying to import. Whether you are a beginner installing your first third-party package or an experienced developer working across multiple environments, this error can appear for a variety of reasons.

In this guide, you will learn the most common causes of this error, how to diagnose each one, and the specific steps to fix it in every scenario.

What Causes This Error?

When Python encounters an import statement, it searches for the module in the following locations (in order):

1. The current directory (the directory of the running script).
2. Directories listed in the PYTHONPATH environment variable.
3. The standard library directories.
4. The site-packages directory (where pip installs third-party packages).

If the module is not found in any of these locations, Python raises a ModuleNotFoundError.

Cause 1: Module Not Installed

The most common cause: the third-party package you are trying to import has not been installed in your current Python environment.

import requests

Output:

Traceback (most recent call last):
  File "main.py", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

Solution: Install the Module With pip

pip install requests

Use python -m pip for reliability

To ensure you install the package for the correct Python interpreter, use:

# ✅ Matches the Python interpreter you're using
python -m pip install requests

# For Python 3 specifically
python3 -m pip install requests

This avoids the common issue where pip is linked to a different Python version than the one running your script.

Verify the Installation

python -m pip show requests

Expected output:

Name: requests
Version: 2.31.0
Summary: Python HTTP for Humans.
Location: /home/user/venv/lib/python3.11/site-packages

If no output appears, the package is not installed in that environment.

Cause 2: Incorrect Module Name (Typo)

Python is case-sensitive, and even a small typo in the module name triggers the error:

# ❌ Typo: missing 'n'
import jso

Output:

ModuleNotFoundError: No module named 'jso'

Solution: Correct the Module Name

# ✅ Correct spelling
import json

Package name vs. import name can differ

Some packages have a different pip install name and import name:

Install Command	Import Statement
pip install Pillow	import PIL
pip install scikit-learn	import sklearn
pip install python-dateutil	import dateutil
pip install opencv-python	import cv2
pip install beautifulsoup4	import bs4

Always check the package's documentation for the correct import name.

Cause 3: Virtual Environment Not Activated

If you installed a package inside a virtual environment but are running your script outside of it (or vice versa), the package will not be found.

Diagnosis

Check which Python interpreter is running:

which python        # Linux/macOS
where python        # Windows

Check if the package is installed for that interpreter:

python -m pip list | grep requests

Solution: Activate the Virtual Environment

# Linux / macOS
source venv/bin/activate

# Windows
venv\Scripts\activate

# Verify
python -m pip show requests

If the package is not installed in the virtual environment, install it after activation:

pip install requests

Cause 4: Wrong Python Version

If you have multiple Python versions installed (e.g., Python 2 and Python 3), pip might install the package for a different version:

# ❌ Installs for Python 2
pip install requests

# But you're running Python 3
python3 main.py   # ModuleNotFoundError

Solution: Match pip to Your Python Version

# ✅ Install for the specific Python version you're using
python3 -m pip install requests

Cause 5: Incorrect Directory Structure (Custom Modules)

When importing your own modules, the error occurs if Python cannot find the file due to an incorrect directory structure or a missing __init__.py file.

Example: Wrong Import Path

myproject/
├── main.py
└── package/
    └── utils.py

# main.py
# ❌ Incorrect: 'mymodule' doesn't exist
from myproject.mymodule import helper

Output:

ModuleNotFoundError: No module named 'myproject.mymodule'

Solution: Fix the Import Path and Add __init__.py

myproject/
├── main.py
└── package/
    ├── __init__.py    ← Add this file
    └── utils.py

# main.py
# ✅ Correct import path
from package.utils import helper

info

Starting with Python 3.3, namespace packages allow imports without __init__.py in some cases. However, explicitly including __init__.py is still the recommended practice for clarity and compatibility.

Cause 6: File Name Shadows a Module

If you name your Python file the same as a standard library or third-party module, Python imports your file instead of the actual module:

project/
├── json.py     ← Shadows the built-in json module
└── main.py

# main.py
import json    # ❌ Imports your json.py, not the built-in module

Solution: Rename Your File

project/
├── data_parser.py   ← Renamed to avoid conflict
└── main.py

# ✅ Now imports the built-in json module
import json

Also delete any cached bytecode:

find . -type d -name __pycache__ -exec rm -rf {} +

Cause 7: IDE Using a Different Interpreter

Your IDE might be configured to use a different Python interpreter than the one where the package is installed.

VS Code

1. Press Ctrl+Shift+P → "Python: Select Interpreter"
2. Choose the interpreter or virtual environment that has the package installed.

PyCharm

1. Go to File → Settings → Project → Python Interpreter
2. Verify or change the interpreter.

Quick Diagnostic Script

Run this script to diagnose the problem:

import sys

module_name = "requests"  # Change to your module

print(f"Python executable: {sys.executable}")
print(f"Python version: {sys.version}")
print(f"Python path:")
for p in sys.path:
    print(f"  {p}")

try:
    mod = __import__(module_name)
    print(f"\n✅ '{module_name}' imported successfully (version: {getattr(mod, '__version__', 'unknown')})")
except ModuleNotFoundError:
    print(f"\n❌ '{module_name}' not found!")
    print(f"   Fix: {sys.executable} -m pip install {module_name}")

Complete Diagnostic Checklist

Step	Action	Command
1	Check Python version	python --version
2	Check which Python is running	which python or where python
3	Check if module is installed	python -m pip show module_name
4	Install the module	python -m pip install module_name
5	Check for typos	Compare your import against the official docs
6	Verify virtual environment	echo $VIRTUAL_ENV or check terminal prompt
7	Check for naming conflicts	Ensure no local file shadows the module
8	Verify IDE interpreter	Check IDE settings for Python interpreter path
9	Clear bytecode cache	find . -name __pycache__ -exec rm -rf {} +

Conclusion

The ModuleNotFoundError is almost always caused by one of these issues: the package is not installed, there is a typo in the import name, the virtual environment is not activated, the wrong Python version is being used, the directory structure is incorrect, or a local file shadows the module name.

The fastest way to diagnose the problem is to run python -m pip show module_name to check if the package is installed for the Python interpreter you are using. Once you identify the root cause, the fix is usually a single command away.