ModuleNotFoundError: No module named X (Fix)

ModuleNotFoundError: No module named 'X' means Python tried to import a module but could not find it.

This usually happens because:

the package is not installed
it is installed in the wrong Python environment
the import name is wrong
a local file is hiding the real package

This guide helps you find the cause quickly and fix it step by step.

Quick fix

python -m pip install requests

Replace requests with the missing module name.

If the package is already installed, check that your terminal, IDE, and virtual environment are all using the same Python interpreter.

What this error means

When Python runs an import like this:

import requests

it searches for that module in places listed in Python’s import path.

If Python cannot find it, you get an error like:

import requests

ModuleNotFoundError: No module named 'requests'

In simple terms, Python is saying:

“I looked for this module”
“I could not find it”
“The name I could not find is the important clue”

Start by reading the missing module name exactly as shown in the error.

Common reasons it happens

The most common causes are:

The package is not installed
The package is installed in a different Python version
A virtual environment is not activated
The import name is wrong
The package name and import name are different
Your IDE is using a different interpreter
A local file name is conflicting with the real package
Your project structure is wrong for local modules

How to fix it step by step

Use this checklist in order.

1. Read the missing module name carefully

If the error says:

ModuleNotFoundError: No module named 'bs4'

then the missing import name is bs4, not necessarily the package name you install.

2. Install the package

Use python -m pip install ... so pip runs with the same Python interpreter:

python -m pip install requests

On some systems, you may need:

python3 -m pip install requests

If you are not sure how installation works, see how to install a Python package with pip.

3. Check which Python is running your script

Run:

python -c "import sys; print(sys.executable)"

This shows the exact Python executable being used.

If your package was installed somewhere else, Python will still say the module is missing.

4. Check whether a virtual environment should be active

If your project uses a virtual environment, activate it before installing packages or running code.

If you need help with that, see how to create and use a virtual environment in Python.

5. Make sure the import name is correct

A package can have one install name and a different import name.

For example:

install pillow but import PIL
install beautifulsoup4 but import bs4

6. Look for local file name conflicts

A file in your project can hide the real package.

For example, if your file is named requests.py, this code can break:

import requests

Rename the file and try again.

7. Restart your terminal or IDE

After installing a package, your editor or terminal session may still be using old settings.

Restart it and run the code again.

Check your Python and pip paths

A very common problem is installing a package with one Python but running code with another.

Run these commands:

python --version
python -m pip --version

Example output:

Python 3.11.6
pip 23.2.1 from /path/to/python3.11/site-packages/pip (python 3.11)

This helps you confirm that:

python points to the version you expect
pip belongs to that same Python

Using python -m pip is safer than plain pip because it reduces the chance of installing into the wrong interpreter.

Virtual environment issues

A virtual environment is an isolated Python environment for one project.

If a package is installed inside a virtual environment, it is usually only available when that environment is active.

Common problems:

You installed the package in a virtual environment, but the environment is not active
Your terminal uses one environment, but your IDE uses another
You created the environment but installed packages globally by mistake

Example workflow:

python -m venv venv

Activate it.

On Windows:

venv\Scripts\activate

On macOS or Linux:

source venv/bin/activate

Then install the package:

python -m pip install requests

If imports still fail, your editor may be using the wrong interpreter.

Import name vs package name

This causes many beginner mistakes.

The name you install is not always the name you import.

Examples:

install pillow → import PIL
install beautifulsoup4 → import bs4

Example:

python -m pip install pillow

Then in Python:

from PIL import Image

Another example:

python -m pip install beautifulsoup4

Then in Python:

import bs4

If the install name and import name do not match, check the package documentation.

If you want to understand imports better, see how import works in Python.

Local file name conflicts

Python checks your project files before some installed packages. Because of that, a local file or folder can shadow a real package.

Problem example

Suppose your project contains a file named requests.py:

import requests
print("Hello")

This can confuse Python because it may try to import your local file instead of the real requests package.

How to fix it

Rename the file to something else, like api_test.py
Also check for folders named requests
Delete generated cache files if needed, such as __pycache__

This kind of conflict can also lead to related errors like AttributeError: module has no attribute.

Debugging commands to try

These commands help you see what Python is using.

python --version
python -m pip --version
python -m pip list
python -c "import sys; print(sys.executable)"
python -c "import sys; print(sys.path)"

What they tell you:

python --version shows the Python version
python -m pip --version shows which Python pip belongs to
python -m pip list shows installed packages
sys.executable shows the exact Python executable
sys.path shows where Python looks for modules

If you want to learn more about the search path, see sys.path explained and the Python sys module overview.

When the module is your own file

Sometimes the missing module is not a package from the internet. It is your own Python file.

Example project:

project/
    main.py
    helper.py

If main.py contains:

import helper

print(helper.say_hello())

then helper.py must exist and contain the function:

def say_hello():
    return "Hello"

Expected output:

Hello

Check these points:

The file is in the correct folder
The spelling matches exactly
The letter case matches exactly
The filename does not contain spaces or invalid characters
If importing from a folder, the project structure is correct

If Python finds the module but not the thing inside it, that is a different problem. See ImportError: cannot import name.

Some import errors look similar but mean different things.

ModuleNotFoundError: No module named 'X'
Python could not find the module at all.
ImportError: cannot import name ...
Python found the module, but not the specific name inside it. See ImportError: cannot import name.
ImportError: No module named X
This is an older style message for similar import problems. See ImportError in Python: causes and fixes.
AttributeError: module has no attribute ...
This can happen after a wrong import or a naming conflict.