Python ModuleNotFoundError: Fix It in 5 Easy Steps (2026)

You install a package, run your script, and Python slaps you with ModuleNotFoundError: No module named 'requests'. It happens to every Python beginner, and it is not a sign that your code is broken. This guide walks you through the Python ModuleNotFoundError “no module named” fix for beginners: five practical steps that solve the error in the vast majority of cases, plus the deeper explanations you need so the error stops coming back.

Before we touch anything, understand the core idea: when Python runs your script, it searches a list of folders for the module you imported. If the module is not installed for the exact Python interpreter that is running your code, you get ModuleNotFoundError. That single sentence explains nearly every case you will ever meet, so every step below is really about making sure the right Python has the right package installed.

In This Guide

What Is ModuleNotFoundError and Why Python Raises It

ModuleNotFoundError is a subclass of ImportError that Python raises when an import statement names a module Python cannot find. A typical traceback looks like this:

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

When Python starts, it builds a list of directories to search called sys.path. This list includes the folder your script lives in, the standard library, and every folder where third-party packages have been installed (usually called site-packages). You can see it yourself:

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

If the module you imported exists in none of those folders, Python gives up and raises ModuleNotFoundError. Beginners almost always hit one of four causes:

The package was never installed. You followed a tutorial that used requests, pandas or pygame, but you never ran pip install for it on this machine.
It was installed for a different Python. Most computers have more than one Python: the system Python, one from python.org, maybe one from Anaconda, plus a version bundled with your editor. Installing a package into one of them does nothing for the others.
The import name does not match the package name. You install pip install scikit-learn but you import sklearn. You install Pillow but import PIL. This catches everyone at least once.
Your file shadows the module. If you name your own script requests.py or random.py, Python finds your file first and everything breaks in confusing ways.

With that map in mind, the five steps below fix the problem in order from most common to least common.

Step 1: Read the Error Message and Identify the Missing Module

The error message tells you the exact module name in quotes. In No module named 'requests', the missing module is requests. Read the quotes carefully, because the fix depends on the exact name.

Check whether it is a standard library module

Python ships with a large standard library (os, sys, json, random, datetime and hundreds more). If the missing name is one of those, you cannot fix it with pip, because there is nothing to install. Instead, something else is wrong. The usual suspects are:

A typo in the import: import jsoon instead of import json.
Your script file is named after a standard module. Rename random.py to something like random_test.py and delete the leftover random.pyc or __pycache__ folder.
You are running an old Python version that lacks the module. zoneinfo, for example, only exists in Python 3.9 and newer. Check your version with python --version.

Check the import name versus the install name

Many packages are imported under a different name than the one pip knows. Common mismatches:

pip install Pillow then import PIL
pip install scikit-learn then import sklearn
pip install beautifulsoup4 then from bs4 import BeautifulSoup
pip install opencv-python then import cv2
pip install PyYAML then import yaml

A quick web search for “pip install modulename” will reveal the right install command whenever you are unsure.

Step 2: Check You Are Using the Right Python Interpreter

This is the single most common cause of the “but I already installed it!” complaint. Run these two commands in your terminal (Command Prompt or PowerShell on Windows, Terminal on macOS and Linux):

python --version
pip --version

On many systems python means Python 2 or points somewhere unexpected, while pip belongs to a different Python 3. Look at the paths that pip --version prints and compare them with python --version. If they do not line up, you have found your problem.

The foolproof pattern that sidesteps this entirely is to call pip as a module of the Python you actually run:

python -m pip --version
python -m pip install requests

python -m pip guarantees the package lands in the same interpreter that python invokes. On systems where only python3 exists, use python3 -m pip install requests instead. Make this a habit and the “installed but not found” class of problems mostly disappears.

While you are at it, confirm which interpreter your editor uses. In VS Code, the Python version shown in the bottom-right status bar is the one that runs your code; the terminal and the editor can easily point at different interpreters. If you keep hitting this wall, our guide to fixing Python not recognized in VS Code walks through PATH and interpreter setup in detail.

Step 3: Install the Missing Package With pip

Once you know the missing module’s real pip name and you are targeting the right interpreter, installing it is one command. Open your terminal and run:

python -m pip install requests

Replace requests with the package you need. Watch the output: pip should show a progress bar and finish with Successfully installed requests-.... If you see Requirement already satisfied instead, pip believes the package is already installed for that interpreter. In that case, re-run the previous step and double-check that the interpreter in your editor matches the one in your terminal.

Upgrade pip if the install fails

Old versions of pip sometimes fail on newer packages. If an install errors out, upgrade pip first and retry:

python -m pip install --upgrade pip
python -m pip install requests

Permission errors: use –user

On macOS and Linux, installing system-wide can trigger a permission error. Adding --user installs the package for your account only, which is usually what you want:

python -m pip install --user requests

Never reach for sudo pip install unless you know exactly why you need it. It can overwrite system-managed Python files and break your operating system’s own tooling.

List what is installed

To see every package the current interpreter knows about, run:

python -m pip list

If your package appears in the list but the import still fails, the script is probably running under a different interpreter, and Step 2 needs another look.

Step 4: Verify the Installation and Re-run Your Script

Before declaring victory, verify the import in isolation. Open a terminal and run Python interactively:

python -c "import requests; print(requests.__version__)"

If that prints a version number, the package is correctly installed for this interpreter. Now run your actual script from the same terminal with the same command:

python app.py

This matters because many beginners install in one terminal and run the script from a different place — a different terminal, an editor button, a Jupyter notebook — where a different Python is in charge. If the import works in the terminal but not in your editor, the editor’s selected interpreter is the problem. In Jupyter, for example, packages must be installed in the notebook’s kernel: run !{sys.executable} -m pip install requests inside a cell, or install ipykernel into your environment and select that kernel.

Step 5: Make the Fix Permanent With Virtual Environments

Installing everything globally works until it does not. Project A needs requests==2.28, project B needs requests==2.31, and suddenly your setup is a mess. Virtual environments give every project its own isolated set of packages, which is how professional Python developers avoid exactly this kind of dependency chaos. The official Python venv tutorial covers the details, but the everyday workflow is short:

# Create a virtual environment in your project folder
python -m venv .venv

# Activate it (Windows)
.venv\Scripts\activate

# Activate it (macOS / Linux)
source .venv/bin/activate

# Now install packages — they stay inside this project
python -m pip install requests

When the environment is active, your terminal prompt shows (.venv) and plain pip and python point inside the environment, so the “wrong interpreter” problem from Step 2 becomes almost impossible.

Record your dependencies

Freeze what you installed into a requirements.txt file so the project works on any machine:

python -m pip freeze > requirements.txt

Later, you (or anyone else) can recreate the environment with python -m pip install -r requirements.txt. If you are managing packages from the terminal, our Ubuntu terminal commands cheat sheet covers the navigation and file commands you will use alongside pip.

Common Variations: VS Code, Jupyter, Typos and Local Files

“It works in the terminal but not in VS Code”

VS Code lets each workspace pick its own Python interpreter, and that interpreter may not be the one in your terminal. Click the Python version in the bottom-right status bar (or press Ctrl+Shift+P and run “Python: Select Interpreter”) and choose the interpreter where you installed the package, or open a VS Code terminal and run python -m pip install requests there.

“It works in the terminal but not in Jupyter”

Jupyter kernels are separate environments. Either install the package with the kernel’s own Python (!{sys.executable} -m pip install requests in a cell, after import sys) or register your virtual environment as a kernel with python -m ipykernel install --user --name=myenv and select it from the Kernel menu.

ModuleNotFoundError after renaming a file

If you named a script email.py, test.py or types.py, Python will import your file instead of the standard library module of the same name, and other libraries that depend on those modules will fail with bizarre errors. Rename the file to anything unique and delete the __pycache__ directory.

Importing your own module from another folder

If the error names your own code — for example No module named 'helpers' when helpers.py sits in a sibling folder — the issue is Python’s search path, not pip. Run your script from the project root, add an empty __init__.py to make folders packages, or use relative imports inside a package. This is a different problem from a missing third-party package, and installing things will not fix it.

Frequently Asked Questions

What is the difference between ModuleNotFoundError and ImportError?

ModuleNotFoundError is a subclass of ImportError. Python raises ModuleNotFoundError when the module itself cannot be found; ImportError covers the broader case, such as when the module exists but something it tries to import fails. In practice, if the message says “No module named”, treat it as a missing-module problem and follow the steps above.

I ran pip install and it says “Requirement already satisfied” — but the import still fails. Why?

You installed the package into a different Python than the one running your script. Use python -m pip install with the exact python command that runs your code, or align your editor’s interpreter with your terminal’s Python. This is the number-one cause of the “already satisfied” paradox.

Should I use pip or pip3?

Either can work, but both suffer from the same ambiguity: you cannot always tell which Python they belong to. python -m pip (or python3 -m pip) is unambiguous and is the recommended form in modern Python. If you are unsure which Python runs your script, always prefer the python -m pip form.

Is it safe to run pip install with sudo?

Avoid it on macOS and Linux. System Python often belongs to the operating system, and overwriting its packages can break system tools. Use --user or, better, a virtual environment instead.

Can I install packages from inside VS Code?

Yes. Open the integrated terminal (Ctrl+`), make sure the right interpreter is selected, and run python -m pip install package-name. Packages installed there are visible to every script run with that interpreter.

How do I fix ModuleNotFoundError in a Docker container or on a server?

Make sure your requirements.txt is complete and that the container image actually runs pip install -r requirements.txt during the build. Most “works locally, fails on the server” cases are a missing or incomplete requirements file, or a Dockerfile that copies code but never installs dependencies.

Key Takeaways

ModuleNotFoundError means Python cannot find the module for the interpreter that is running your code — the module is missing, or it was installed for a different Python.
Read the quoted module name in the error first: typos, shadowing filenames, and import-name versus install-name mismatches explain many cases with no install needed.
Use python -m pip install package-name so the package always lands in the Python you actually run.
Verify with python -c "import package" before re-running your script, and make sure your editor uses the same interpreter as your terminal.
Virtual environments plus a requirements.txt file make the fix permanent and keep projects from stepping on each other.

Conclusion

The Python ModuleNotFoundError “no module named” fix for beginners comes down to one habit: always know which Python is running your code, and always install packages into that exact Python with python -m pip. Work through the five steps in order — read the error, check the interpreter, install with pip, verify the import, and lock it in with a virtual environment — and you will resolve the error in minutes instead of losing an evening to it. Next time the red traceback appears, you will know exactly where to look.