ModuleNotFoundError is one of the most common Python exceptions developers face. Whether you’re building microservices, data pipelines, or automating tasks, running into No module named can stop progress cold.

This guide shows you how to fix ModuleNotFoundError in Python, fast. From basic mistakes to interpreter issues, we’ll cover every angle—so you can get back to shipping code.

If you’re wondering why Python errors are so frequent in cross-language stacks, check out Stop Writing Python Like JavaScript over on MadDosh.

Table of Contents

What Is ModuleNotFoundError in Python?

ModuleNotFoundError is a subclass of ImportError, introduced in Python 3.6. You’ll see it when Python can’t find the module you’re trying to import.

ModuleNotFoundError: No module named 'requests'

At its core, Python’s import system looks for modules in directories listed in sys.path. If the module isn’t there—or the environment isn’t set up correctly—you’ll get this error.

For a deeper understanding of how Python resolves modules, read the official Python Import System documentation.

Why Does Python Raise ModuleNotFoundError?

There are six main reasons why Python can’t find a module:

1. The module isn’t installed.
2. You’re using the wrong Python interpreter or virtual environment.
3. The module is installed, but Python can’t find it due to path issues.
4. You’re importing it incorrectly (wrong relative or absolute import).
5. You’re facing Python 2 vs Python 3 conflicts.
6. The module installation is corrupted or incomplete.

If you’re working with multiple environments or containers, these mistakes are easy to make. Our 2025 Developer Report highlights how tooling complexity is still a top pain point for engineers.

How to Fix ModuleNotFoundError in Python (Step-by-Step)

Below is a fast debugging guide. Start here and work down.

1. Check the Module Name for Typos

It sounds basic, but typos are the #1 reason for ModuleNotFoundError.

# Wrong
import reqests

# Correct
import requests

Python module names are case-sensitive, even if your OS isn’t. If you’re unsure about naming conventions, see the official Python Style Guide (PEP 8).

2. Confirm the Module Is Installed

Run this in your terminal—not the Python shell:

pip show requests

No output? It’s not installed.

Install It for Python 3

python3 -m pip install requests

For a broader comparison of pip, pipenv, and poetry, DZone’s guide on Python Dependency Management Tools is solid.

3. Verify You’re Using the Right Python Environment

Multiple environments can create confusion. Check which Python interpreter is active:

import sys
print(sys.executable)

If the path isn’t what you expect, activate the correct virtual environment.

Virtual Environment Activation

# venv on Linux/macOS
source venv/bin/activate

# venv on Windows
venv\Scripts\activate

For Poetry and Pipenv usage, this Python.org tutorial on venv explains best practices.

4. Resolve Python 2 vs Python 3 Conflicts

You might install a module under Python 2, but run Python 3 (or vice versa).

Check Versions

python --version
python3 --version

Install Explicitly for Python 3

python3 -m pip install requests

For organizations migrating off Python 2, DZone has a detailed Python 2 to Python 3 Migration Guide.

5. Fix Absolute and Relative Imports

Bad imports inside your project can lead to ModuleNotFoundError.

Example Structure

project/
├── main.py
└── module/
    └── utils.py

If you run main.py incorrectly, imports may fail.

Correct Approach

Use absolute imports, or run as a module:

python -m module.utils

Also, understand Python’s module search path via sys.path:

import sys
print(sys.path)

For more examples of common Python mistakes, including import issues, check this guide.

6. Fix Jupyter Notebook Path Problems

Jupyter often runs under a different interpreter. Confirm your kernel:

import sys
print(sys.executable)

Install the package in that environment:

/path/to/python -m pip install requests

To avoid Jupyter-Python mismatches, follow the official Jupyter installation guide.

7. Docker Containers and CI/CD Environments

If your Python project runs inside Docker or CI/CD, you need to install packages there.

Dockerfile Example

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install -r requirements.txt

COPY . .

CMD ["python", "main.py"]

8. IDE Configuration: PyCharm and VS Code

Make sure your IDE is running the correct interpreter.

PyCharm

Settings > Project > Python Interpreter

VS Code

Ctrl + Shift + P → Python: Select Interpreter

For optimizing IDE configuration in Python, we recommend the Python.org IDE overview.

9. Watch for File Name Conflicts

Don’t name your scripts after popular modules (e.g., requests.py). It can shadow the real library.

If You Did…

• Rename the file.
• Delete __pycache__ folders:

find . -name '__pycache__' -exec rm -r {} +

This happens often when people transition from other languages, like in our post on Stop Writing Python Like JavaScript.

10. Reinstall the Module

If the installation is broken:

pip uninstall requests
pip install requests

For scientific packages, sometimes Conda works better:

conda install numpy

For Python dependency lockfiles and reproducibility, check DZone’s article on Python Dependency Hell.

Fast Debugging Checklist for ModuleNotFoundError

• ✅ Typos in the import statement
• ✅ Verify module installation via pip show
• ✅ Confirm interpreter with sys.executable
• ✅ Watch for Python 2 vs Python 3
• ✅ Correct relative vs absolute imports
• ✅ Jupyter and Docker environments
• ✅ IDE interpreter setup
• ✅ Module name conflicts (file vs library)
• ✅ Reinstall if corrupt
• ✅ Debug sys.path

How to Prevent ModuleNotFoundError in the Future

• Use virtual environments (venv, pipenv, poetry).
• Document dependencies (requirements.txt, Pipfile.lock).
• Automate environment setup with CI/CD.
• Run pre-flight scripts to check dependencies.

For a deeper dive into developer workflows, check out The 2025 Developer Report.

Frequently Asked Questions (FAQ)

What causes ModuleNotFoundError in Python?

The error happens when Python can’t find the module because it’s missing, installed in the wrong environment, or imported incorrectly.

How do I fix No module named ‘requests’?

Install the requests module using:

python3 -m pip install requests

Make sure you’re in the correct virtual environment.

Why do I get ModuleNotFoundError in Jupyter Notebook?

Jupyter may be using a different Python interpreter. You need to install the module in the same environment Jupyter runs in or register your virtualenv as a kernel.

Solve It Once—Never Deal with ModuleNotFoundError Again

The ModuleNotFoundError in Python is one of those errors that looks simple but can spiral if you’re not methodical. Whether it’s a missing install, the wrong interpreter, or a misconfigured environment, knowing how to debug it fast keeps your momentum intact.

Python thrives when your environment is clean and your workflow is disciplined. If you’re serious about leveling up—not just fixing errors, but writing cleaner, scalable code—start thinking about your environment, your tools, and your mindset.

At MadDosh, we’re building resources, tools, and gear for developers who don’t just want to survive in codebases—they want to own them.

🛠️ Check out the MadDosh merch shop for gear designed by devs, for devs. Whether you’re battling import errors or deploying to prod, do it in style.