How to Fix "Module Not Found" Error in Python Easily (2026 Complete Guide)

You write your script, hit run, and Python throws this at you:

ModuleNotFoundError: No module named 'requests'

It’s one of the most common Python errors — and honestly, one of the most frustrating, especially when you think you already installed the package. The good news is that once you understand what’s actually happening, you can fix it in minutes.

This guide covers every real cause of the “Module Not Found” error and gives you the exact fix for each one — whether you’re on Windows, macOS, or Linux, using VS Code, PyCharm, Jupyter Notebook, or just the terminal. We’ll also cover some trickier situations like virtual environment conflicts, file naming mistakes, circular imports, and the newer PEP 668 issue that’s tripping up a lot of developers on Ubuntu and macOS in 2026.

Let’s get into it.

What Is the “Module Not Found” Error in Python?

The Error Message Explained

When Python can’t locate a module you’re trying to import, it raises a ModuleNotFoundError. The message always looks something like this:

ModuleNotFoundError: No module named 'pandas'

or with a longer traceback:

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

The key part is No module named 'xxx' — Python is telling you it searched everywhere it knows to look and couldn’t find the module you asked for.

ModuleNotFoundError is a specific subtype of ImportError. It was introduced in Python 3.6 to give a clearer, more specific message than the generic ImportError it replaced. If you’re on Python 2 (which you really shouldn’t be in 2026), you’ll see ImportError instead.

ImportError vs ModuleNotFoundError — What’s the Difference?

These two errors are related but not the same:

Error	What It Means
`ModuleNotFoundError`	Python cannot find the module at all — it doesn’t exist in any location Python knows to check
`ImportError`	Python found the module, but something went wrong while loading it (e.g., a missing attribute or a broken dependency inside)

ModuleNotFoundError is a subclass of ImportError. So every ModuleNotFoundError is an ImportError, but not every ImportError is a ModuleNotFoundError.

How Python Finds Modules (sys.path)

Before you can fix the error, it helps to understand what Python does when you write import something. Python searches three locations in order:

sys.modules — a cache of already-imported modules (checked first, fastest)
The standard library — built-in modules like os, sys, json
Every directory in sys.path — this includes the script’s directory, any PYTHONPATH directories, and the site-packages folder of the active Python installation

If your module isn’t in any of those locations, you get the error.

You can inspect sys.path yourself anytime:

import sys
for path in sys.path:
    print(path)

This is one of the most useful diagnostic steps when you’re stuck. Understanding where Python is looking gives you the power to figure out exactly why it’s not finding your module.

8 Most Common Causes of “Module Not Found” Error

The error almost always comes from one of these eight causes. Work through them in order — most people find their issue in the first three.

1. The Package Simply Isn’t Installed

This is the most common cause. Python has a standard library built in, but third-party libraries like requests, pandas, numpy, or flask need to be installed separately.

How to check:

pip list | grep requests     # macOS/Linux
pip list | findstr requests  # Windows

The fix:

pip install requests

Or better — use this form to make sure you’re installing into the right Python (more on why this matters shortly):

python -m pip install requests

If you’re working with data and keep hitting this with pandas or numpy, our pandas tutorial for beginners covers the full setup from scratch, including environment configuration.

2. A Typo or Wrong Case in the Import Statement

Python is case-sensitive. import Numpy is not the same as import numpy. This catches developers off guard constantly, especially when switching between languages.

# WRONG
import Numpy        # ModuleNotFoundError
import Requests     # ModuleNotFoundError
import Pandas       # ModuleNotFoundError

# CORRECT
import numpy
import requests
import pandas

Also worth knowing: the name you use to install a package is sometimes different from the name you use to import it. Here are the most common mismatches that trip people up:

Install Command	Correct Import
`pip install Pillow`	`import PIL`
`pip install scikit-learn`	`import sklearn`
`pip install beautifulsoup4`	`import bs4`
`pip install python-dateutil`	`import dateutil`
`pip install opencv-python`	`import cv2`
`pip install pyyaml`	`import yaml`
`pip install python-dotenv`	`import dotenv`

When in doubt, check the package’s page on pypi.org — it always shows the correct import name in the usage section.

3. The Wrong Python Version (or pip Version)

This one is subtle and very common. You might have multiple Python versions on your system — Python 3.11, Python 3.13, maybe even an old Python 2.7. When you run pip install requests, it might install to Python 3.11, but your script runs on Python 3.13.

Check for a mismatch:

python --version       # e.g. Python 3.13.2
pip --version          # e.g. pip 24.3 from /usr/lib/python3.11/... ← MISMATCH

See the problem? pip points to Python 3.11’s environment, but python runs 3.13. Any package installed via pip install won’t be visible to your Python 3.13 scripts.

The definitive fix — always use this:

python -m pip install requests

This ties pip directly to whichever python is currently active, eliminating the version mismatch problem entirely. Make this a habit.

4. Virtual Environment Not Activated (Or the Wrong One Is Active)

If you’re using a virtual environment — which you should be — this is the second most common cause after the package simply not being installed.

Quick explanation: A virtual environment is an isolated Python environment for a specific project. Packages installed inside one virtual environment are invisible to other environments (and to global Python). If you install a package outside the venv, or forget to activate it, Python won’t find it.

How to check if a venv is active:

# macOS/Linux — look for (venv) at the start of your terminal prompt
(venv) user@machine:~/project$

# Windows — same, you'll see the env name in the prompt
(venv) C:\Users\user\project>

# Or run:
which python   # macOS/Linux
where python   # Windows
# If it shows a path inside your venv directory, you're good

How to create and activate a virtual environment:

# Step 1: Create the venv
python -m venv venv

# Step 2: Activate it
source venv/bin/activate      # macOS/Linux
.\venv\Scripts\activate       # Windows

# Step 3: Install packages inside the activated venv
pip install requests flask pandas

# Step 4: Run your script
python script.py

Important: You need to activate the virtual environment every time you open a new terminal session. It doesn’t persist automatically.

5. Custom/Local Module Not Found (sys.path or Wrong Directory)

If you’re importing your own module — a .py file you wrote yourself — Python needs to know where to find it.

Say you have this structure:

my_project/
├── main.py
└── utils/
    └── helpers.py

If you run python main.py from inside my_project/, and main.py contains from utils import helpers, it will work because my_project/ is in sys.path. But if you run it from a different directory, Python won’t know to look inside my_project/.

Quick fix — add the module’s directory to sys.path:

import sys
sys.path.append('/path/to/my_project')
import helpers

Better fix — run scripts with the -m flag from the project root:

# Instead of:
python utils/helpers.py

# Use:
cd my_project
python -m utils.helpers

Best fix — use a proper package structure with __init__.py files and install your own package in development mode:

pip install -e .

This registers your package with Python properly so imports work from anywhere.

6. PEP 668 — “Externally Managed Environment” Error (Linux & macOS 2024+)

This is a newer issue that’s tripping up a lot of developers in 2026, particularly on Ubuntu 23.04+, Debian 12+, Fedora 38+, and macOS with Homebrew Python.

You’ll see something like this when you try pip install:

error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, use apt.
hint: See PEP 668 for the full story.

What’s happening: PEP 668 lets operating systems protect their system Python from accidental package overwrites via pip. The OS is blocking the install — so the package never gets installed — and then your import fails.

The correct fix — use a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install requests   # Now works fine

Alternative for system-wide tools:

sudo apt install python3-requests   # Debian/Ubuntu

For CLI tools specifically: use pipx, which manages an isolated environment automatically:

pipx install black

What you should not do is blindly add --break-system-packages to every pip command — it exists for edge cases and can cause real damage to your OS Python installation.

7. Python 3.12/3.13 Breaking Changes — distutils Removed

If you’re getting this specific error:

ModuleNotFoundError: No module named 'distutils'

It’s not a missing package — it’s a Python version compatibility issue. distutils was removed from Python’s standard library in Python 3.12. Older packages that relied on it will fail to install or import.

The fix:

# Upgrade the package to a modern version
pip install --upgrade numpy

# Or if a specific older version is required, pin to a compatible one
pip install "numpy>=1.24"

If you need distutils functionality, install setuptools, which now provides it:

pip install --upgrade setuptools

8. Conda / Anaconda Environment Conflicts

If you’re using Anaconda or Miniconda, conda environments add another layer. A package installed via conda install lives in the conda environment’s package directory, while a package installed via pip install goes somewhere else. Mixing them can cause confusion.

Check which environment is active:

conda info --envs
# The active one has an asterisk (*)

Activate the right environment:

conda activate myenv
conda install pandas   # Install inside the active conda env

If you’re mixing pip and conda: always install conda packages first, then pip packages. And only use pip install after activating the conda environment — running pip from outside will install to the wrong location.

Step-by-Step Fixes for “Module Not Found” Error

Here’s the practical walkthrough. Start at the top and work down until your error is gone.

Fix 1: Install the Missing Package

# The safest way — always use python -m pip
python -m pip install requests

# Verify it installed:
pip show requests

# Install multiple packages at once:
pip install requests flask pandas numpy

# Install from requirements.txt:
pip install -r requirements.txt

Fix 2: Correct the Import Name

Check pypi.org for the correct import name. Also double-check spelling and case in your code:

# WRONG
import SKLearn
from PIL import image   # lowercase 'i' — wrong

# CORRECT
import sklearn
from PIL import Image   # uppercase 'I' — correct

Fix 3: Use python -m pip (Not Just pip)

# Always prefer this
python -m pip install package_name

# Verify pip and python match:
python -m pip --version
# Should show a path containing your Python version

Fix 4: Create, Activate, and Install Inside a Virtual Environment

# Create
python -m venv venv

# Activate
source venv/bin/activate      # macOS/Linux
.\venv\Scripts\activate       # Windows

# Confirm you're inside the venv
which python   # Should show a path inside your venv folder

# Install
pip install your_package

# Run your script
python your_script.py

Fix 5: Add Your Module’s Directory to sys.path

When importing your own modules:

import sys
import os

# Add the project root to sys.path
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

import my_module   # Now Python can find it

Fix 6: Reinstall a Corrupted Package

Sometimes a package installation gets interrupted or corrupted:

pip uninstall requests
pip cache purge           # Clear pip's download cache
pip install requests      # Reinstall clean

Fix 7: Update an Outdated Package

pip install --upgrade package_name

Fixing “Module Not Found” in VS Code

VS Code is the most common place this error catches developers off guard. The reason? VS Code runs your Python using its own configured interpreter — which might be completely different from the one in your terminal.

How to check which interpreter VS Code is using:

Look at the bottom-left status bar in VS Code. It shows the active Python version (e.g., “Python 3.13.2”). Click it to change it.

Step-by-step fix:

Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS) to open the Command Palette
Type “Python: Select Interpreter” and press Enter
A list of available Python interpreters appears — look for the one with venv in its path (e.g., ./venv/bin/python)
Select it
Open a new terminal inside VS Code (`Ctrl+“) — this ensures the terminal also uses the selected interpreter
Run your script again

If your venv doesn’t appear in the list:

Make sure your venv folder is inside your project folder
Click “Enter interpreter path…” and manually navigate to ./venv/bin/python (macOS/Linux) or .\venv\Scripts\python.exe (Windows)

After changing the interpreter: Always restart the VS Code terminal. The old terminal session might still point to the previous Python.

If you run into other tricky bugs in VS Code, our guide on how to debug Python code step by step walks through VS Code’s debugger in detail.

Fixing “Module Not Found” in PyCharm

PyCharm manages a Python interpreter per project. If a package is installed in one environment but your project uses another interpreter, PyCharm won’t find it.

Step-by-step fix:

Go to File → Settings (Windows/Linux) or PyCharm → Preferences (macOS)
Navigate to Project → Python Interpreter
You’ll see the current interpreter and a list of installed packages
If the package you need isn’t listed, click the + button to install it directly from PyCharm
If the interpreter is wrong, click the gear icon → “Add Interpreter” → choose your virtual environment

For Jupyter Notebooks in PyCharm:

PyCharm Professional has a separate interpreter setting for Jupyter notebooks. Make sure the “Jupyter servers” configuration points to the same interpreter as your project.

Note: Packages installed via the system terminal won’t appear in PyCharm unless PyCharm’s interpreter points to the same Python environment where you installed them.

Fixing “Module Not Found” in Jupyter Notebook

Jupyter uses kernels — each kernel is a separate Python environment. The kernel running your notebook might be completely different from the Python in your terminal, even if you installed the package from your terminal.

The most common scenario:

# In terminal:
pip install pandas
# ✅ Installs pandas into your active Python

# In Jupyter cell:
import pandas
# ❌ ModuleNotFoundError — because Jupyter uses a different Python!

Fix 1: Install the package from inside Jupyter

# In a Jupyter notebook cell:
!pip install pandas

The ! prefix runs a terminal command from within Jupyter. This installs pandas into the kernel’s Python environment directly.

Fix 2: Register your virtual environment as a Jupyter kernel

This is the proper, permanent solution:

# Step 1: Activate your virtual environment
source venv/bin/activate   # macOS/Linux
.\venv\Scripts\activate    # Windows

# Step 2: Install ipykernel inside it
pip install ipykernel

# Step 3: Register it as a named kernel
python -m ipykernel install --user --name myproject --display-name "My Project"

# Step 4: Restart Jupyter

After restarting Jupyter, click the kernel name (top-right of the notebook), select “Change Kernel”, and pick “My Project”. Now your notebook runs on the same Python where your packages are installed.

Fixing “Module Not Found” in Google Colab

Google Colab is a cloud Jupyter environment. Each session starts fresh, so packages that aren’t part of Colab’s default setup need to be installed every session.

# In a Colab cell:
!pip install requests

# Then import:
import requests

For multiple packages:

!pip install requests beautifulsoup4 pandas

If you have a requirements.txt in your Google Drive:

from google.colab import drive
drive.mount('/content/drive')
!pip install -r /content/drive/MyDrive/requirements.txt

Colab tip: Run the !pip install cell before the import cells. And if you’ve restarted the runtime, you’ll need to re-run the install cell — packages don’t persist between sessions.

OS-Specific Fixes

Windows

Windows is especially prone to the pip/Python version mismatch issue because it’s common to install Python from multiple sources (python.org, Microsoft Store, Anaconda).

Check what’s on your PATH:

where python
where pip

Use the Python Launcher to target a specific version:

py -3.13 -m pip install requests   # Install for Python 3.13
py -3.13 script.py                 # Run with Python 3.13

Windows Store Python vs python.org Python: If you installed Python from the Microsoft Store, it lives in AppData. This can conflict with a python.org installation. Uninstall one or always use py -3.x to be explicit.

macOS

macOS ships with its own Python (used by the OS), plus you might have Homebrew Python and python.org Python. Never use the system Python for your projects.

PEP 668 applies to Homebrew Python (since 2024):

# Wrong — will fail with PEP 668 error
brew install python
pip3 install requests

# Right — use a virtual environment
python3 -m venv .venv
source .venv/bin/activate
pip install requests

If you see command not found: python: On modern macOS, the command is python3, not python. Add this to your ~/.zshrc if you want the shorter command:

alias python=python3
alias pip=pip3

Linux (Ubuntu/Debian/Fedora)

PEP 668 is most aggressively enforced on Linux. On Ubuntu 23.04+ and Debian 12+, every pip install on the system Python will be blocked.

The right workflow on Ubuntu:

# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Now pip installs work fine
pip install flask pandas requests

# Or for system-wide packages, use apt
sudo apt install python3-numpy

For WSL2 (Windows Subsystem for Linux): Follow the Linux instructions. Be careful about running Python files from the Windows filesystem (/mnt/c/...) inside WSL — path mixing can cause unexpected issues. Keep your project files in the Linux home directory.

Relative vs Absolute Imports — A Common Source of Confusion

When you write your own Python packages, import style matters.

Absolute imports specify the full path from the project root:

# In myproject/utils/helpers.py
from myproject.models import User          # Absolute import

Relative imports use dots to navigate relative to the current file:

# In myproject/utils/helpers.py
from ..models import User                  # Relative import (go up one level)
from . import another_util                 # Same package

The key rule: Relative imports only work inside a package (a directory with __init__.py). If you try to use relative imports in a standalone script (e.g., python helpers.py), you’ll get:

ImportError: attempted relative import with no known parent package

Fix: Either use absolute imports, or run your module with the -m flag:

# Works for relative imports
python -m myproject.utils.helpers

PEP 8 recommends absolute imports for readability in most cases. Only use relative imports when you have a deeply nested package and absolute paths become unwieldy.

If you’re building more complex Python structures, our object-oriented programming in Python guide covers how to structure classes and packages properly.

PYTHONPATH Issues

PYTHONPATH is an environment variable that tells Python where to look for modules, in addition to the default locations. If you’re importing custom modules and don’t want to modify sys.path inside your code, PYTHONPATH is the cleaner option.

Check your current PYTHONPATH:

echo $PYTHONPATH    # macOS/Linux
echo %PYTHONPATH%   # Windows

Set it temporarily (current session only):

# macOS/Linux
export PYTHONPATH="/path/to/my/project:$PYTHONPATH"

# Windows
set PYTHONPATH=C:\path\to\my\project;%PYTHONPATH%

Set it permanently:

# Add to ~/.bashrc or ~/.zshrc (macOS/Linux)
echo 'export PYTHONPATH="/path/to/project:$PYTHONPATH"' >> ~/.zshrc
source ~/.zshrc

Caution: PYTHONPATH is a global setting and can cause unexpected behavior across different projects. Virtual environments are almost always a better, cleaner solution. Use PYTHONPATH sparingly and document it when you do.

File Naming Conflicts — A Silent Bug

This one gets developers at every level. If you name your Python file the same as a module you’re trying to import, Python will find your file first instead of the real module.

Example of the problem:

project/
├── requests.py     # ← You named your file 'requests.py'
├── main.py         # main.py does: import requests

When main.py does import requests, Python finds your requests.py instead of the requests library. The result is a confusing error — sometimes ModuleNotFoundError, sometimes AttributeError, depending on what your file contains.

Common dangerous file names to avoid:

random.py (conflicts with random module)
math.py (conflicts with math module)
json.py (conflicts with json module)
requests.py (conflicts with requests library)
flask.py (conflicts with flask)
pandas.py (conflicts with pandas)
os.py (conflicts with os module)

The fix: Rename your file. If you’ve already run code with the conflict, also delete the .pyc file and __pycache__ directory — Python might have cached the wrong module:

rm -rf __pycache__
rm *.pyc

Circular Import Issues

A circular import happens when Module A imports Module B, and Module B also imports Module A. Python can get stuck trying to load both at the same time.

What it looks like:

# module_a.py
from module_b import func_b

def func_a():
    return "A"

# module_b.py
from module_a import func_a   # ← Circular!

def func_b():
    return "B"

Running either file raises:

ImportError: cannot import name 'func_a' from partially initialized module 'module_a'

Fix 1: Move the import inside the function (deferred import)

# module_b.py
def func_b():
    from module_a import func_a   # Only imported when func_b() is called
    return "B" + func_a()

Fix 2: Restructure to remove the circular dependency

The cleanest fix. Create a third module that holds shared code, and both modules import from that instead of from each other.

shared.py      ← holds shared utilities
module_a.py    ← imports from shared.py
module_b.py    ← imports from shared.py

Fix 3: Use TYPE_CHECKING for type hints

If your circular dependency is only for type annotations:

from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from module_b import ModuleB   # Only imported during type checking, not at runtime

This is a clean pattern for large projects where type hints create import cycles. Our Python decorators guide covers more advanced module patterns that help keep code organized.

Advanced Troubleshooting

Diagnose with sys.executable and pip show

When you’re not sure which Python or which environment you’re in:

import sys
print(sys.executable)          # Full path to the Python being used
print(sys.version)             # Python version
print(sys.path)                # All directories Python searches

Then verify where pip installed your package:

pip show requests
# Output includes:
# Location: /path/to/site-packages

Compare the location from pip show with the paths in sys.path. If the package location isn’t in sys.path, that’s your problem.

Check if a Package Imported Correctly

try:
    import requests
    print("✅ requests imported successfully from:", requests.__file__)
except ModuleNotFoundError:
    print("❌ requests not found in this environment")

Using uv — The Modern Python Package Manager (2026)

uv is a Rust-based package manager from Astral (the team behind the ruff linter). As of early 2026, it’s running version ~0.10.x and has become the fastest-growing tool in the Python ecosystem. It’s 10–100x faster than pip and handles environment management cleanly.

# Install uv
pip install uv

# Create a virtual environment
uv venv

# Install packages
uv pip install requests flask

# Run a script
uv run script.py

uv avoids many common ModuleNotFoundError pitfalls by managing environments and Python versions as a single integrated workflow. If you’re starting a new project, it’s worth trying.

“Module Not Found” in Real Projects

Flask Projects

Flask beginners often encounter this error because they run their script from the wrong directory, or they forget to activate the virtual environment their Flask installation is in.

# Wrong: running from a parent directory
python myapp/app.py

# Right: navigate into the project first
cd myapp
source venv/bin/activate   # Activate the venv
flask run                   # Or: python app.py

If you’re building a Flask project from scratch, our complete Flask beginner’s guide covers environment setup, file structure, and common import patterns. And if you’re building a login system with Flask, check out our Flask login system guide — it includes the full virtual environment setup.

Django Projects

Similar to Flask — Django projects should always be run with the virtual environment activated. If you’re deciding between the two, our Django vs Flask comparison breaks down when each makes sense.

Data Science (pandas, numpy, matplotlib)

The classic Jupyter + conda mismatch scenario:

# Correct workflow
conda create -n datasci python=3.13
conda activate datasci
conda install pandas numpy matplotlib
pip install ipykernel
python -m ipykernel install --user --name datasci
jupyter notebook   # Then select "datasci" kernel

Automation Scripts

Automation scripts commonly use packages like requests, yagmail, selenium, or pyautogui. These all need to be installed in the same environment where your script runs. If you’re building email automation, our Python email automation guide covers the full setup including the packages involved.

For CSV file handling with automation scripts, check out our Python CSV file handling guide — it covers reading and writing data files which often involves the csv and pandas modules.

Common Beginner Mistakes

Here are the patterns that cause this error most often for beginners:

Running pip install without the venv activated — the package goes into global Python, not your project’s venv. Always check your prompt for the (venv) prefix first.
Naming a file after a built-in module — creating math.py or requests.py shadows the real module. Rename it immediately.
Installing with bare pip instead of python -m pip — on systems with multiple Python versions, these can point to different places.
Forgetting ! in Jupyter Notebook — pip install pandas in a cell doesn’t work; !pip install pandas does.
Using the wrong Jupyter kernel — the kernel name appears in the top-right corner of the notebook. If it doesn’t match your venv, switch it.
Not activating the venv in a new terminal session — activation doesn’t persist. Every new terminal needs source venv/bin/activate.
Mixing conda and pip randomly — install conda packages first, then pip packages. Never install pip packages before activating the conda environment.
Running a script from the wrong directory — if your module is at project/utils.py and you run python project/main.py from outside project/, relative imports fail. cd into project/ first.

For other common Python errors, our IndentationError fix guide is a good companion read — these errors often appear together when setting up a new project.

Best Practices to Prevent This Error

Follow these habits and you’ll rarely see ModuleNotFoundError again:

1. Always use a virtual environment

python -m venv venv
source venv/bin/activate   # Every time you start a new session

2. Use python -m pip instead of bare pip

python -m pip install package_name

3. Keep a requirements.txt

pip freeze > requirements.txt           # Save your current packages
pip install -r requirements.txt         # Reproduce the environment anywhere

4. Pin Python versions with .python-version

echo "3.13" > .python-version

Tools like uv and pyenv respect this file and use the correct Python version automatically.

5. Document your setup

Add a README.md to every project with setup instructions:

## Setup
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python main.py

6. Use pyproject.toml for modern projects

[project]
name = "myproject"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31",
    "pandas>=2.1",
]

This makes dependency management explicit and reproducible.

7. Register Jupyter kernels properly

Don’t rely on the default Jupyter kernel. Register your venv:

python -m ipykernel install --user --name myproject --display-name "My Project"

If you’re building something more complex — like a chatbot or interactive Python project — check out our Python chatbot guide, which covers the full setup including dependencies.

Quick Diagnostic Flowchart

When you hit ModuleNotFoundError, run through this:

Is the package installed?
  → No → python -m pip install package_name → Done

  → Yes ↓
Is your virtual environment activated?
  → No → Activate it, reinstall if needed → Done

  → Yes ↓
Does your IDE use the right Python interpreter?
  → No → Select the venv interpreter in VS Code / PyCharm → Done

  → Yes ↓
Is the import name spelled correctly and with correct case?
  → Check pypi.org for correct import name → Fix typo → Done

  → Yes ↓
Is this a Python 3.12+ project with distutils issues?
  → pip install --upgrade the package → Done

  → Still failing ↓
Check sys.path — is the module's directory listed?
  → No → Add via sys.path.append() or fix project structure
  → Yes → Run pip show package_name and compare location to sys.path

Summary — All Fixes at a Glance

Cause	Quick Fix
Package not installed	`python -m pip install package_name`
Wrong pip/Python version	Always use `python -m pip install`
Virtual environment not active	`source venv/bin/activate` (macOS/Linux) or `.\venv\Scripts\activate` (Windows)
Wrong IDE interpreter	VS Code: “Python: Select Interpreter”; PyCharm: Project Settings
Typo or wrong case	Check correct import name on pypi.org
PEP 668 blocked (Linux/macOS)	Use venv, or `apt install python3-xyz`
distutils removed (Python 3.12+)	`pip install --upgrade package_name`
Wrong Jupyter kernel	Register venv as kernel, restart Jupyter
Conda/pip conflict	Install in the active conda env
Custom module not found	Fix `sys.path` or use proper package structure
File naming conflict	Rename your file; delete `__pycache__`
Circular import	Defer the import or refactor shared code

FAQ

Q: Why does Python say “No module named” when I already installed it?

Almost certainly a Python/pip version mismatch or a virtual environment issue. Run python -m pip show package_name — if it shows the package, your pip and Python match. If not, use python -m pip install package_name to install to the exact Python your script runs on. Also verify your venv is activated.

Q: How do I fix ModuleNotFoundError in VS Code?

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P), type “Python: Select Interpreter”, and choose the interpreter inside your virtual environment (look for a path containing /venv/). Then restart the VS Code terminal.

Q: How do I fix “No module named” in Jupyter Notebook?

Either run !pip install package_name in a Jupyter cell (installs to the current kernel’s Python), or register your virtual environment as a Jupyter kernel: python -m ipykernel install --user --name myenv. Then restart Jupyter and switch to that kernel.

Q: What’s the difference between ImportError and ModuleNotFoundError?

ModuleNotFoundError means Python couldn’t find the module at all. ImportError means Python found the module but something went wrong loading it (like a missing sub-dependency or a broken internal attribute). ModuleNotFoundError is a subclass of ImportError, introduced in Python 3.6.

Q: How do I fix ModuleNotFoundError in PyCharm?

Go to File → Settings → Project → Python Interpreter. Make sure the interpreter points to your virtual environment. You can install missing packages directly from that screen by clicking the + button.

Q: Why does pip install work but the import still fails?

pip and python are pointing to different Python installations. Use python -m pip install package_name instead — this guarantees pip installs to the exact Python interpreter your scripts use.

Q: How do I fix the “externally managed environment” error on Ubuntu?

Create a virtual environment: python3 -m venv .venv && source .venv/bin/activate. Then install inside it. Alternatively, use sudo apt install python3-packagename for system-wide packages.

Q: Why do I get ModuleNotFoundError: No module named 'distutils'?

distutils was removed from Python’s standard library in Python 3.12. The package you’re trying to install depends on an outdated version that still uses it. Fix: pip install --upgrade package_name. If that doesn’t work, pip install setuptools provides a compatibility shim.

Q: How do I fix ModuleNotFoundError for my own custom Python module?

Make sure you’re running your script from the project root directory. Use sys.path.append('/path/to/module') in your code, or structure your project as a proper package with __init__.py and install it in development mode with pip install -e ..

Q: What’s the best way to prevent this error in future projects?

Three habits prevent 95% of cases: (1) always work inside a virtual environment, (2) always use python -m pip install instead of bare pip, and (3) keep a requirements.txt using pip freeze > requirements.txt.

Conclusion

The “Module Not Found” error in Python is one of those problems that feels mysterious the first time — and completely obvious once you understand the cause. Python is just telling you it can’t find a module in the locations it knows to look. The fix is almost always one of a handful of things: the package isn’t installed in the right place, pip and Python aren’t linked to the same environment, your IDE is using the wrong interpreter, or there’s a naming conflict somewhere.

The habit that prevents most of these issues? Always work inside a virtual environment, always use python -m pip install, and always check your IDE’s interpreter settings when something doesn’t work. Get those three right and you’ll spend a lot less time chasing this error.

If you’re still stuck after working through this guide, check your sys.path output — it tells you exactly where Python is looking. Compare that to the output of pip show package_name — it tells you exactly where the package was installed. If those two locations don’t overlap, that’s your problem, and you now know how to fix it.

For more Python troubleshooting, our step-by-step Python debugging guide is the next best read — it covers how to use breakpoints, the debugger, and systematic error diagnosis so you can catch issues before they become blocking problems.

Recommended Resources

Here are the official and most reliable references for everything covered in this guide:

Python Import System — Official Documentation — the authoritative explanation of how Python finds and loads modules
Python venv — Official Documentation — complete guide to creating and managing virtual environments
pip Documentation — official pip reference including install, uninstall, and troubleshooting
PEP 668 — Externally Managed Environments — explains the “externally managed environment” error and why it exists
VS Code Python Environments Guide — Microsoft’s official guide for configuring Python interpreters in VS Code
PyCharm Python Interpreter Configuration — JetBrains’ official guide to setting up interpreters in PyCharm
uv Documentation — documentation for the modern, fast Python package and project manager
PyPI — Python Package Index — search for correct package names and import names for any third-party library