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

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:

import jso

Output:

ModuleNotFoundError: No module named 'jso'

Solution: Correct the Module Name

import json

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

source venv/bin/activate

venv\Scripts\activate

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:

pip install requests

python3 main.py   # ModuleNotFoundError

Solution: Match pip to Your Python Version

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

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

from package.utils import helper

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

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

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

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.