Tutorials & How-to Guides

Fixing ModuleNotFoundError in Python (Beginner-Friendly Guide)

Published

7 months ago

November 19, 2025

Fixing ModuleNotFoundError in Python (Beginner-Friendly Guide)

Fix modulenotfounderror in python step by step with this beginner‑friendly guide. Learn why the module not found error happens and how to solve it using pip install, virtual environments, and simple checks.

You copy code from a tutorial, press run, and the program crashes. At the bottom of the red text, you see:

ModuleNotFoundError: No module named 'something'

This doesn’t feel very clear, but it is fixable. In simple terms, Python tried to load a module but couldn’t find it, so it stopped. A typical message looks like:

Traceback (most recent call last):

  File "script.py", line 1, in <module>

    import requests

ModuleNotFoundError: No module named 'requests'

modulenotfounderror in python is one of the most common beginner issues. This guide explains what it means, why it happens, and how to fix it step by step, even if you have just started learning.

What Is ModuleNotFoundError in Python and Why Do You See It

When Python reaches an import line, it searches several folders for that module. If it cannot find it, it raises a ModuleNotFoundError and stops your script.

Example:

import requests  # but 'requests' is not installed

response = requests.get("https://example.com")

print(response.status_code)

If requests Is not installed, running this file will end with:

ModuleNotFoundError: No module named 'requests'

This often happens when you:

Follow a YouTube tutorial

Run a project from GitHub

Copy code from a blog or class notes

The code assumes some modules are already installed. Your system does not have them yet, so you see a module-not-found error.

Reading the error message line by line

A full traceback might look like this:

Traceback (most recent call last):

  File "app.py", line 3, in <module>

    import requests

ModuleNotFoundError: No module named 'requests'

Key parts:

File "app.py": Which file failed

line 3: where the import failed

import requests: the exact line of code

ModuleNotFoundError: No module named 'requests': the missing module name

The final line is your clue. The text inside quotes, here'requests', is what Python could not find. Knowing that name is the first step to fixing the problem.

ModuleNotFoundError vs ImportError: what is the difference?

Both are import-related errors, but:

ModuleNotFoundError: Python could not find the module.

ImportError: Python found the module, but something inside it went wrong.

Simple analogy:

ModuleNotFoundError: module ‘house’ does not exist.

ImportError: the house exists, but the door is jammed.

You will see ModuleNotFoundError more often when starting.

Most Common Reasons You Get a Module Not Found Error

Most real problems fall into a few simple categories.

The module is not installed at all.

Many beginners think all modules come with Python. They do not. Packages like requests, pandas, numpy, flask, and many others must be installed first.

If you write:

import requests

Without installing it, you will get ModuleNotFoundError. The pip install command downloads and adds the package so Python can find it.

Using the wrong Python or pip version

One computer can have multiple Python versions. For example:

python might point to Python 3.8

python3 might point to Python 3.12

The same goes for pip and pip3. If pip installs the module for Python 3.8 but if you run the script with Python 3.12, you get a modulenotfounderror no module message, even though you ran pip install.

Virtual environment issues and modules installed in a different env

A virtual environment is a separate folder where Python keeps project‑specific packages. It isolates one project from another.

Typical problem:

You install a package within a single virtual environment.

You run your code in a different environment, or with the global Python.

In that context, Python has never heard of the package.

Some IDEs auto‑create virtual environments, which makes this easy to miss.

Typos in the module name or the wrong import path

Small mistakes cause big problems:

import requets   # typo

import Requests  # wrong case

Both will trigger ModuleNotFoundError. Imports are case sensitive.

For packages with submodules:

from mypackage.utils import helper

The folder and file structure must match exactly. Any mismatch looks like a missing module.

IDE or interpreter misconfigured (VS Code, PyCharm, Jupyter)

Each tool chooses a Python interpreter:

VS Code: interpreter shown in the status bar

PyCharm: project interpreter in settings

Jupyter: kernel selection at the top right

If the tool is pointing at a Python that does not have the module installed, you see ModuleNotFoundError even if you installed it in a different interpreter.

How to Fix ModuleNotFoundError in Python Step by Step

Follow this checklist in order. Replace requests with your actual module name.

Step 1: Confirm which Python you are actually using

In your terminal or command prompt:

python --version

If that fails or shows an old version, try:

python3 --version

You should see something like Python 3.11.7. Remember this version number. Recent versions, including Python 3.13, all use the same basic import behavior.

Step 2: Check your pip version and match it to Python

Run:

pip --version

pip3 --version

python -m pip --version

Look at the end of the output. It will say something like (python 3.11). That tells you which Python pip belongs to. You want the pip that matches the Python you use to run your script.

Using It python -m pip is a safe pattern, because it ties pip to that specific Python.

Step 3: Install or reinstall the missing module with pip install

Try:

pip install requests

If that does not work or you are on a system that uses Python 3 by default:

pip3 install requests

Recommended pattern:

python -m pip install requests

If you know your exact version:

python3.11 -m pip install requests

If the install finishes without errors, the module should now be available to that Python.

Step 4: Fix “pip not found” or “pip is not recognized” errors

If you see messages like pip is not recognized or command not found:

On Windows: reinstall Python from the official installer and check “Add Python to PATH”.

On macOS: in Terminal, run python3 -m ensurepip --upgrade.

On Linux (Ubuntu example): run sudo apt install python3-pip.

On any system, this can also help:

python -m ensurepip --upgrade

Then close and reopen your terminal and try python -m pip --version again.

Step 5: Create and use a virtual environment correctly

In your project folder:

python -m venv venv

Activate it.

On Windows:

venv\\Scripts\\activate

On macOS or Linux:

source venv/bin/activate

Your prompt should now start with (venv).

Inside this environment, install your module:

pip install requests

Then run your script with:

python script.py

To see what is installed in this environment:

pip list

Step 6: Verify the module is installed and importable

After installation, check:

pip show requests

Then test a quick import:

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

If that prints OK Without errors, the module is installed correctly in this environment. Now run your actual script in the same terminal or command prompt window.

Step 7: Fix typos and incorrect import paths in your code

Carefully compare your import lines with the package name from the Python Package Index or the tutorial.

Watch for cases like:

pip install beautifulsoup4 but from bs4 import BeautifulSoup

pip install scikit-learn but from sklearn import datasets

For your own files, if you have a structure like:

project/
- main.py
- utils/
  - helpers.py

Then inside main.py You would write:

from utils import helpers

If the import name does not match the folder and file names, you will get a module not found error even when the file exists.

Fixing ModuleNotFoundError in Popular Tools: VS Code, PyCharm, and Jupyter

Sometimes the module is installed, but your editor uses a different Python.

VS Code: choosing the correct Python interpreter

Open VS Code.

Press Ctrl+Shift+P (or Cmd+Shift+P on macOS).

Type Python: Select Interpreter and press Enter.

Pick the interpreter that matches your virtual environment or the Python version where you ran. python -m pip install.

Look at the bottom status bar to confirm the chosen interpreter. Then rerun your script.

PyCharm: setting the project interpreter and packages

Open PyCharm.

Go to File > Settings (or PyCharm > Preferences on macOS).

Select Project: your_project > Python Interpreter.

Choose the interpreter that has your packages, or click the gear icon to add your venv.

PyCharm will show a list of installed packages. You can install the missing ones from that screen and then re-run your code.

Jupyter Notebook: using a kernel with the right environment

Inside the notebook, look at the top right for the kernel name (for example, Python 3).

Click it and choose Change kernel.

Select the kernel for your virtual environment.

If your env is not listed, you may need to register it first from inside that environment:

pip install ipykernel

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

Then restart Jupyter, pick the myenv kernel, and rerun your cells.

Advanced and Less Common ModuleNotFoundError Cases

If the simple fixes do not help, you might be in one of these less common situations.

When a module is not on PyPI at all

Not all modules are available with a simple pip install package_name. Some are:

Downloaded from GitHub or another site

Installed from a local folder

In those cases, you might see commands like:

pip install git+https://github.com/user/repo.git

pip install /path/to/local/folder

As a beginner, you will not face this often, but it explains why you pip install name sometimes fail to find a package.

System Python vs user Python and path confusion

On Linux and macOS, there is often a “system Python” used by the operating system. You might install your own Python from another source.

Modules installed in the system Python will not appear in your user Python, and vice versa. To avoid this:

Pick one central Python installation for learning.

Always use virtual environments.

Always use python -m pip with that Python.

Simple Habits to Avoid ModuleNotFoundError in the Future

A few habits will keep modulenotfounderror in Python from coming back.

Always use a virtual environment for each project

Create: python -m venv venv

Activate it

Install packages inside it

This keeps each project’s dependencies separate and easier to manage.

Keep a requirements.txt file with your project

After you install your packages:

pip freeze > requirements.txt

On a new machine, or for a friend:

pip install -r requirements.txt

This prevents missing modules from causing surprises when you move code.

Match your Python and pip commands every time

Use a consistent pattern:

python -m pip install package_name

python script.py

Using the same python for both pip and running your code keeps everything in sync across versions.

Document install steps when sharing code or tutorials

When you share a project:

Write down the Python version

List the required packages

Mention how to create and activate the virtual environment

Clear instructions save time for everyone and reduce module-not-found errors.

Quick FAQ About ModuleNotFoundError for Beginners

Why do I still get ModuleNotFoundError after running pip install?

Most likely:

You installed the package for a different Python version.

You are running code in the wrong virtual environment.

Your IDE is using another interpreter.

Check python --version, python -m pip --version, and your IDE’s interpreter settings.

How is ImportError different from ModuleNotFoundError?

ModuleNotFoundError: Python could not find the module.

ImportError: Python found the module, but something else went wrong while loading it.

ModuleNotFoundError is a specific kind of ImportError.

How do I fix ModuleNotFoundError in VS Code?

Install the package with python -m pip install package_name.

In VS Code, use Python: Select Interpreter the same Python.

Restart the terminal inside VS Code.

Rerun your script.

How do I know which Python my IDE or notebook is using?

Add this to a script or cell:

import sys

print(sys.executable)

print(sys.version)

This prints the exact Python path and version the tool is using.

Conclusion

A ModuleNotFoundError in Python means Python couldn’t find the module you imported. The leading causes are missing installs, incorrect Python or pip versions, virtual environment conflicts, typos, and IDE configuration issues. The general fix pattern is clear: check which Python you’re running, which pip you’re using, install the package in the right environment, and make sure your editor points to that same interpreter.

Work through the steps in this guide one by one, rather than guessing. Apply them to the project that is failing right now. Once it runs, you will be much more confident handling errors and ready to move on to more Python topics.

Up Next

How To Install Windows 11 On Unsupported CPU (Safe, Tested Methods)

Don't Miss

How to Use Google Gemini Mini Without Google Account (Guest Mode Guide)

Arslan Ahmad

Arslan Ahmad is the founder of TechBasics101 and a technology writer focused on Windows troubleshooting, software performance, and practical PC optimization guides. He has over three years of hands-on experience in SEO and content strategy and has contributed technology and digital marketing content to established publications such as Chiang Rai Times. His work is rooted in real-world testing, daily system use, and solving common issues users face after Windows updates, upgrades, driver changes, or software conflicts. Rather than relying on benchmarks or theory alone, Arslan focuses on responsiveness, usability, and fixes that actually improve how a PC feels in everyday use. At TechBasics101, he publishes clear, experience-driven guides designed to help readers understand technology better, troubleshoot problems with confidence, and make informed decisions without unnecessary complexity or risky tweaks.

Techbasics