How to Fix ModuleNotFoundError in Python in 2026: Every Cause, Checked in Order
Fix ModuleNotFoundError by matching your interpreter, virtual environment, and package install, in that order.
ModuleNotFoundError is the error Python shows when an import statement asks for a module it cannot find. It stops your script before it runs, which makes it feel serious. In most cases it is not a broken program. It is a mismatch between the Python interpreter running your code and the place where the package was installed. Work through the causes in order, and you will usually find the fix in a few minutes.
Direct answer: ModuleNotFoundError means Python cannot find the module named in your import. Check the interpreter first, then check whether you have the right virtual environment active. Next, confirm the package is installed for that same interpreter, check the import name for typos, and check that your own files are in a folder Python can reach. Fixing the environment mismatch solves most cases.
What ModuleNotFoundError Really Means
When Python runs an import, it searches a list of folders called sys.path. That list includes the folder of your script, the standard library, and the site-packages folders of the active environment. If none of those folders contains the module, Python raises ModuleNotFoundError. The Python documentation describes this error as a subclass of ImportError, raised when a module cannot be located.
That detail matters because it tells you where to look. The module may exist on your computer, but in a different environment. Or it may not be installed at all. Or the name in your code may not match the package name. Each of those problems looks the same in the traceback, so guessing wastes time. A short, ordered check is faster than reinstalling packages at random.
Read the last line of the traceback first. It names the missing module exactly. Copy that name, then work down the checklist below. Do not skip the interpreter check. It is the most common cause, and it explains why pip says a package is already satisfied while your script still fails.
The Checklist, in Order
Follow these steps in order. Stop as soon as one step explains the error, fix it, and run your script again. If you are learning the wider workflow, read Python virtual environments explained alongside this checklist.
- Check which interpreter is running. Run python –version and which python, or where python on Windows, in the same terminal or editor you use to run the script. Then check the interpreter selected in VS Code or PyCharm. If the editor uses a different interpreter from your terminal, pip and your script are talking to two different Pythons.
- Check whether the right virtual environment is active. Look for the environment name in your terminal prompt, or check the interpreter path in your editor. If you created a venv for the project but never activated it, your script runs with the system Python and cannot see project packages. Activate the environment, then run the script again.
- Check whether the package is installed for that interpreter. Run python -m pip list and look for the package name. Installing with plain pip can target a different Python, so always use python -m pip with the same python you run. If the package is missing, install it with python -m pip install package-name.
- Check the import name for typos. The install name and the import name are not always the same. For example, you install Pillow but import PIL, and you install scikit-learn but import sklearn. Check the package documentation for the correct import name, and check your spelling letter by letter.
- Check your own files and folder layout. If the missing module is your own code, Python must be able to reach it. Running a script from the wrong folder is a common cause. Run it from the project root, and make sure a package folder contains an __init__.py file where one is needed. Avoid naming your own file the same as a standard library module, such as random.py or email.py, because that file can shadow the real module.
- Check system versus user installs. On some systems, pip installs to a user folder while the interpreter looks elsewhere, or a system package manager owns the Python install. Use python -m pip show package-name to see the location pip used. If the location does not match your interpreter, reinstall with python -m pip install package-name into the active environment instead of mixing install methods.
Causes at a Glance
Use this table to match what you see with the most likely fix. It covers the causes above in a form you can scan quickly when the error appears again.
| Cause | What you notice | Fix first |
|---|---|---|
| Wrong interpreter | pip says satisfied, script still fails | Match the editor and terminal interpreter |
| Inactive virtual environment | Works on one machine, fails on another | Activate the project venv before running |
| Package in another environment | pip list shows it in a different Python | Install with python -m pip for the running Python |
| Typo or wrong import name | Install name differs from import name | Check the docs for the correct import name |
| Path or file layout problem | Your own module is missing, not a library | Run from the project root and check folder layout |
Exact Commands to Run
Start with three diagnostic commands, all using the same python you use to run the script. First, run python –version to confirm the version. Second, run python -c “import sys; print(sys.executable)” to see the exact interpreter path. Third, run python -m pip list to see what that interpreter can actually import. Those three answers remove most guesswork.
If the package is missing, install it for that interpreter with python -m pip install requests, replacing requests with your package name. Then verify with python -c “import requests” and confirm there is no error. If the install succeeds but the import still fails, recheck the interpreter path. You may have installed into one Python and tested with another.
For your own modules, print the search path with python -c “import sys; print(sys.path)” and check whether your project folder is listed. If it is not, change to the project root before running, or adjust how you launch the script. For deeper tracing problems, see how to debug Python code, which covers breakpoints and traceback reading in VS Code and PyCharm.
How to Prevent It With Virtual Environments
A virtual environment gives each project its own interpreter copy and its own site-packages folder. That separation stops one project from breaking another, and it makes the install location obvious. In Python 3.15, the built-in venv module remains the standard starting point, and tools such as uv and Poetry build on the same idea for faster installs or dependency locking.
Create the environment once per project with python -m venv .venv, activate it, then install from a requirements file with python -m pip install -r requirements.txt. Commit the requirements file, not the environment folder. A teammate who follows the same two steps gets the same packages, which removes a whole class of “works on my machine” errors.
Make the habit automatic. Activate the environment before you install anything, and check the interpreter in your editor when you open a project. If you are still building your Python skills, the how to learn Python roadmap puts environments, debugging, and packaging in a sensible learning order.
Frequently Asked Questions
Why does pip say requirement already satisfied but Python still fails?
This almost always means pip and your script use different interpreters. Pip installed the package for one Python, while your editor or terminal runs another. Run python -m pip list with the same python that runs your script. If the package is absent there, install it with python -m pip install and test the import again.
What is the difference between ModuleNotFoundError and ImportError?
ModuleNotFoundError is a specific kind of ImportError. Python raises it when the named module cannot be found at all. ImportError is broader and can also cover a module that was found but failed during import, for example because of a broken file inside it. The Python documentation explains this relationship, and the distinction helps you decide whether to fix the environment or inspect the module itself.
Do I need a virtual environment for a small script?
You do not need one for a tiny script with no third party packages, but it is still good practice. A venv costs seconds to create and keeps project packages separate from system Python. Once a script needs even one library, an environment makes installs repeatable and avoids conflicts with other projects or system tools that depend on Python.
Why can Python not find my own module in the same project?
Python searches the script folder and the folders on sys.path, not every folder in your project. Running from the wrong directory, missing package files, or a file that shadows a standard library name can all break the import. Run from the project root, check the folder layout, and rename any local file that shares a name with a standard library module.
Should I use sudo pip install to fix the error?
No, avoid sudo pip install in almost every case. It can install packages into system Python, create permission problems, and conflict with your operating system package manager. Use a virtual environment and install as your normal user instead. That keeps system Python clean and makes the project portable to another machine.
Conclusion
ModuleNotFoundError looks alarming, but it usually points to one simple mismatch: the wrong interpreter, an inactive environment, or a package installed somewhere else. Check the interpreter first, confirm the environment, verify the install with python -m pip, and check the import name. Keep each project in its own virtual environment, and this error will become rare, quick to diagnose, and easy to fix. Write the three diagnostic commands down, or keep this checklist bookmarked, so the next time the error appears you start with evidence instead of reinstalling packages and hoping.
