Fixing ModuleNotFoundError in Python: Simple Step‑by‑Step Fix for Beginners

This guide explains how to fix ModuleNotFoundError in Python in clear, simple steps. It explains what the error means, why it occurs, and what actions resolve it in most cases.

The guide is written for beginners who copy code from tutorials or GitHub, run it, and see a red error message like:

ModuleNotFoundError: No module named 'something'

Python reports that it tried to import a module but couldn’t find it, so it stopped running the program.

A typical traceback looks like this:

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

The message can look scary, but it usually has a simple cause and a simple fix.

What ModuleNotFoundError in Python Means

When Python reads an import line, it searches a list of folders for that module. If the module is not in any of those folders, Python raises a ModuleNotFoundError and stops the script.

Example:

import requests  # 'requests' is not installed
response = requests.get("https://example.com")
print(response.status_code)

If requests Is not installed for that Python interpreter, the script ends with:

ModuleNotFoundError: No module named 'requests'

This situation often appears when code is taken from:

• YouTube or online courses
• GitHub projects
• Blog posts or classroom material

The original author already installed the needed packages. On a new system, those packages do not exist yet, so Python cannot find them.

How to Read the Error Message

A full traceback usually contains all the information needed to identify the problem.

Example:

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

Key points in this message:

• File "app.py" shows the file where the error happened
• line 3 shows the exact line number that failed
• import requests shows the import statement that caused the error
• No module named 'requests' names the missing module

The module name in quotes, here 'requests', is the important part. That is the package Python could not locate.

ModuleNotFoundError vs ImportError

Both errors relate to imports, but they do not mean the same thing.

• ModuleNotFoundError appears when Python cannot find the module at all
• ImportError appears when Python finds the module, but something breaks while loading it

Simple comparison:

• ModuleNotFoundError: the module is missing
• ImportError: the module exists, but something inside it is broken or misused

Beginners see ModuleNotFoundError more often because missing dependencies or typos often cause it.

Main Causes of ModuleNotFoundError in Python

Most cases fall into a few common patterns. Understanding these explains most errors.

1. The Module Was Never Installed

Python ships with a standard library, but many popular packages are separate installs. Examples include:

• requests
• pandas
• numpy
• flask

When an import is written like this:

import requests

And the package was never installed, Python raises ModuleNotFoundError.

In general, external packages are installed with the pip tool. That tool downloads and registers packages so Python can see them.

2. Wrong Python Version or Wrong Pip

Many systems have multiple Python versions. For example:

• python might refer to Python 3.8
• python3 might refer to Python 3.12

The same pattern appears with pip:

• pip might talk to Python 3.8
• pip3 might talk to Python 3.12

If pip installs the package for one version of Python, but the script runs in another, Python cannot find the module. The result is a ModuleNotFoundError in Python, even though pip install was already used.

A common situation:

1. pip install requests is run from the terminal
2. The program is started with python3 script.py
3. The program reports No module named 'requests'

In this case, pip and Python refer to different interpreters.

3. Virtual Environments and Different Install Locations

A virtual environment (often called a venv) is a separate folder that contains its own Python and packages. Each project can have its own venv.

A frequent problem looks like this:

• The package is installed inside one virtual environment
• The script runs in a different environment, or with the global system Python
• The active interpreter has no record of that package

Some editors create and use a virtual environment in the background. If the terminal and the editor use different environments, the same import can work in one place and fail in another.

4. Typos or Wrong Import Paths

Misspelled module names or incorrect case are a common source of ModuleNotFoundError.

Examples:

import requets   # typo
import Requests  # wrong case

Both lines fail because imports are case sensitive and must match the real package name.

Imports that involve subfolders also need exact paths. For example:

from mypackage.utils import helper

In this case, the folder structure must match:

• mypackage/
  • utils/
    • helper.py

Any mismatch in name or path appears to be a missing module to Python.

5. Editor or Interpreter Settings (VS Code, PyCharm, Jupyter)

Modern tools let users choose which Python interpreter to use. If the tool points to a Python that does not have the needed package installed, imports fail.

Common examples:

• Visual Studio Code shows the interpreter in the status bar
• PyCharm has a “Project Interpreter” setting
• Jupyter uses “kernels” to choose the Python environment

If a package is installed in one interpreter but the editor uses another, a ModuleNotFoundError occurs even though the package was successfully installed elsewhere.

How to Fix ModuleNotFoundError in Python: A Simple Checklist

The steps below fix the error in most beginner cases. The example module name is requests, but any missing module name can be used instead.

Step 1: Check Which Python Is Running

In a terminal or command prompt, run:

python --version

If that fails or shows Python 2, try:

python3 --version

The output should look like:

Python 3.11.7

This version of Python should be used to install and run the code.

Step 2: Check Pip and Match It to Python

Next, check which Python pip is connected to:

pip --version
pip3 --version
python -m pip --version

The end of the line often looks like:

(python 3.11)

This shows which Python interpreter pip belongs to. The goal is to use the same Python for both installing packages and running scripts.

A safe pattern uses:

python -m pip --version

This command ties pip directly to the chosen python command.

Step 3: Install or Reinstall the Missing Module

If the module is truly missing, install it with pip. Try:

pip install requests

If that does not work or installs into another Python version, use:

pip3 install requests

The recommended pattern for most systems is:

python -m pip install requests

If a specific Python version is required, use:

python3.11 -m pip install requests

After a successful install, that module should be available to that Python interpreter.

Step 4: Fix Problems Where Pip Is Not Found

Sometimes the terminal responds with messages like pip is not recognized or command not found. In that case, pip itself is not set up.

Common fixes:

• On Windows, reinstall Python from the official installer and check “Add Python to PATH”
• On macOS, run in Terminal:

  python3 -m ensurepip --upgrade
  

• On Linux (Ubuntu example), install pip with:

  sudo apt install python3-pip
  

On many systems, running the following also helps:

python -m ensurepip --upgrade

After that, close and reopen the terminal and check again with:

python -m pip --version

If that works, pip is now ready to install packages.

Step 5: Create and Use a Virtual Environment

A virtual environment keeps project packages separate from system-wide packages. This avoids conflicts and hidden installs.

In the project folder, create a venv:

python -m venv venv

Activate it.

On Windows:

venv\Scripts\activate

On macOS or Linux:

source venv/bin/activate

The terminal prompt usually changes to show (venv) at the start.

Inside this active environment, install the needed module:

pip install requests

Then run the script:

python script.py

To see all installed packages in that venv:

pip list

This pattern keeps code and dependencies easier to manage.

Step 6: Confirm the Module Is Installed and Can Be Imported

To confirm the package is visible to Python, use:

pip show requests

Then test a short import from the same environment:

python -c "import requests; print('OK')"

If OK appears without an error, Python successfully imported the module. The same terminal session should now be used to run the full script.

Step 7: Fix Typos and Import Names

If the installation is correct and the error persists, the import line may be incorrect.

Compare the import lines with the official package names:

• Install: pip install beautifulsoup4
  Import: from bs4 import BeautifulSoup
• Install: pip install scikit-learn
  Import: from sklearn import datasets

The name used  pip install can be different from the name used in import. Documentation on the Python Package Index (PyPI) page for the project usually shows the correct pattern.

For imports inside a project, folder and file names must match. Example project:

• project/
  • main.py
  • utils/
    • helpers.py

Inside main.py  The import is usually:

from utils import helpers

If the folder is spelled Utils or the file is helper.py The import must match that exact name. Any difference leads to a module not found error, even if the file is present.

Fixing ModuleNotFoundError in Popular Tools

Sometimes the package is installed correctly, but the editor or notebook points to another interpreter. This section covers standard tools.

Visual Studio Code: Selecting the Correct Python

In VS Code, you can quickly change the Python interpreter.

Steps:

1. Open VS Code
2. Press Ctrl+Shift+P (Windows or Linux) or Cmd+Shift+P (macOS)
3. Type Python: Select Interpreter and press Enter
4. Pick the interpreter that matches the venv or Python used with python -m pip install ...

The chosen interpreter appears in the bottom status bar. After changing it, reopen the terminal inside VS Code and rerun the script.

PyCharm: Project Interpreter and Packages

PyCharm manages a separate interpreter for each project.

Steps:

1. Open PyCharm
2. Go to File > Settings (or PyCharm > Preferences on macOS)
3. Click Project: your_project > Python Interpreter
4. Pick the interpreter or venv that has the installed packages

PyCharm shows a list of installed packages for that interpreter. Missing packages can be added from this screen, then the script can be run again.

Jupyter Notebook: Choosing the Right Kernel

Jupyter uses kernels to pick the Python environment.

Steps:

1. Open the notebook
2. Look at the top right corner to see the kernel name, such as Python 3
3. Click it, then select Change Kernel
4. Choose the kernel that belongs to the correct venv or Python install

If the environment does not appear in the list, it can be registered from inside that environment:

pip install ipykernel
python -m ipykernel install --user --name myenv

After restarting Jupyter, a new kernel named myenv will appear. Selecting that kernel connects the notebook to the correct environment.

Less Common Causes of ModuleNotFoundError

Most beginners will solve the error with the steps above. A few advanced cases appear in larger projects or special setups.

Modules That Are Not on PyPI

Some projects are not listed on the Python Package Index, so pip install package_name does not find them.

These projects may require commands such as:

pip install git+https://github.com/user/repo.git
pip install /path/to/local/folder

In such cases, the project’s own documentation usually explains how to install the package.

System Python vs User Python

On Linux and macOS, the operating system often comes with its own Python. Users may install another Python from python.org, Homebrew, or another source.

If a package is installed in the system Python, it will not be visible in the user’s custom Python, and the reverse is also true.

To keep things simple:

• Choose one central Python installation for learning
• Always use virtual environments for projects
• Use the pattern python -m pip in that environment

This reduces confusion and avoids mixing system tools with development work.

Habits That Prevent ModuleNotFoundError in Python

A few simple habits help keep these errors from returning.

Use a Virtual Environment for Every Project

For each new project:

python -m venv venv

Then activate it and install packages inside that venv.

This practice keeps each project’s packages separate and avoids hidden conflicts.

Keep a requirements.txt File.

After installing the necessary packages:

pip freeze > requirements.txt

On another machine, or when sharing with others:

pip install -r requirements.txt

This file records all packages and versions, so others can set up the same environment without having to guess.

Match Python and Pip Every Time

Use the same command for both installing and running:

python -m pip install package_name
python script.py

This pattern reduces version mix-ups and keeps packages connected to the correct interpreter.

Document Setup Steps When Sharing Code

When releasing a project or teaching others:

• Mention the Python version, such as Python 3.11
• List all required packages
• Describe how to create and activate the virtual environment

Clear setup notes help others avoid ModuleNotFoundError and related issues.

Quick FAQ: ModuleNotFoundError in Python

Why does ModuleNotFoundError appear after running pip install?

Common reasons include:

• The package was installed for a different Python version
• The code runs in the wrong virtual environment
• The IDE or notebook uses another interpreter

Checking these commands helps:

python --version
python -m pip --version

Then confirm that the editor or Jupyter kernel uses the same Python.

How is ImportError different from ModuleNotFoundError?

• ModuleNotFoundError means Python cannot find the module
• ImportError means Python found the module, but another problem occurred while loading it

ModuleNotFoundError is a type of ImportError that provides a more specific message.

How can ModuleNotFoundError be fixed in VS Code?

Use this pattern:

1. Install the package with python -m pip install package_name in a terminal
2. In VS Code, run Python: Select Interpreter and pick the same Python
3. Restart VS Code’s built-in terminal
4. Run the script again

How can the active Python interpreter be identified?

Add this code to a script or notebook cell:

import sys
print(sys.executable)
print(sys.version)

This prints the path to the Python binary and the version number. That path should match the interpreter used by pip to install packages.

Conclusion

A ModuleNotFoundError in Python signals that Python could not find a module listed in an import statement. import Statement. In most cases, the cause is one of the following:

• The module was never installed
• Pip installed it for a different Python version
• The script runs in the wrong virtual environment
• The import name has a typo or wrong case
• The editor or notebook uses a different interpreter

The fix usually follows a simple pattern: check which Python is in use, connect pip to that Python, install the package in the correct environment, and confirm that the editor or notebook points to the same interpreter.

Working through these steps methodically builds confidence and reduces frustration. Over time, these habits make it easier to handle errors, manage packages, and focus on learning Python itself.