How to fix ModuleNotFoundError in Python (2026)

Overview

ModuleNotFoundError is one of the most common Python errors, but the cause is not always “the package is missing”. Python raises it when the import system cannot locate a module on its search path. That can happen because the package is not installed, it was installed into a different Python interpreter or virtual environment, the import name is wrong, your script is being run from the wrong folder, or your own project files are laid out in a way Python does not treat as importable. A good fix starts with diagnosis rather than immediately running pip install. First read the full error line and note the exact name after No module named. Then confirm which Python executable is running your script and which pip belongs to that same interpreter. If the missing item is a third-party package, install it into that exact environment. If it is one of your own files, check the folder structure, package layout, and whether you are using relative or absolute imports correctly. The key point is that Python imports are environment-specific. A package can be installed on the machine and still be invisible to the interpreter launching your code. Once you identify whether the problem is naming, installation, environment, or project structure, the fix is usually straightforward.

Who this is for

Python users troubleshooting import errors in local scripts, virtual environments, IDEs, notebooks, containers, or shared development setups.

What you’ll need

• Access to the terminal or command prompt used to run Python
• The full error message
• Your project files
• Permission to install packages in the target environment if needed

Before you start

Copy the exact error message, including the module name and the command you used to run the script. If you use an IDE, notebook, Docker container, or virtual environment, note that too, because the Python interpreter there may be different from the one in your normal terminal.

Step-by-step

1. 1

   Read the exact module name in the error

   Look at the final line of the traceback and identify the exact text after "No module named". Then compare it with your import statement character by character, including spelling, capitalisation, dots for submodules, and hyphens versus underscores.

   Why: Many import failures are simple naming issues. The install name and import name are sometimes different, and Python module names are exact.

2. 2

   Check which Python interpreter is running your code

   In the same environment where the error happens, run a command that prints the Python executable path and version, such as asking Python itself for sys.executable and sys.version. If you are using an IDE or notebook, check its selected interpreter or kernel in the settings.

   Why: A package installed for one interpreter is not available to another. This is the most common cause when something works in one terminal but fails in an editor, test runner, or notebook.

3. 3

   Check whether the package is installed in that interpreter

   Use that same Python interpreter to query installed packages, for example by running pip through Python rather than calling pip on its own. If the package does not appear, install it using that interpreter. If it does appear, compare the package name with the import name and review whether you are importing the correct top-level module.

   Why: Running pip directly can target a different Python installation. Calling pip through the same Python executable avoids that mismatch.

4. 4

   If it is your own module, verify the project structure

   Check that the file you want to import actually exists, that you are running the script from the expected location, and that package folders are arranged properly. If you are inside a package, prefer running the package as a module rather than running a deep file directly. Review whether you need an absolute import from the package root or a relative import within the package.

   Why: Local import errors often come from launching a file in a way that changes Python's import path, rather than from a missing dependency.

5. 5

   Look for name conflicts in your project

   Search your working folder for files or folders that have the same name as standard library modules or installed packages, such as requests.py, json.py, or a folder named like the package you want. Rename conflicting files and remove stale cache files if needed, then try again.

   Why: Python may import your local file first, which can block or confuse the real package import.

6. 6

   Check virtual environments, containers, and notebooks separately

   If you use a virtual environment, activate it before running Python or installing packages. In Jupyter, confirm the notebook kernel matches the environment where you installed the package. In Docker or other containers, install the package in the image or running container that executes the code, not only on the host machine.

   Why: These tools isolate environments by design, so packages installed elsewhere are invisible unless the correct environment is active.

7. 7

   Reinstall or recreate the environment if it is inconsistent

   If the package should be present but imports still fail, uninstall and reinstall the package in the correct environment, or recreate the virtual environment from your dependency file. Then run a minimal import test from the same interpreter used by the application.

   Why: Broken environments, partial installs, and stale dependency states can leave import metadata inconsistent.

Why this works

Python resolves imports by searching known locations tied to the active interpreter and the current package context. Fixing ModuleNotFoundError works when you align three things: the exact module name, the environment that contains it, and the way your project is being executed so that the import path is correct.

Common mistakes to avoid

• Running pip instead of using the same interpreter that runs the code
• Installing a package globally but running the script inside a virtual environment
• Assuming the package name on the package index is the same as the import name
• Running a file directly from inside a package and breaking relative imports
• Creating a local file with the same name as a package or standard library module

Troubleshooting

Compare your options

Alternatives

• Use a dependency manager such as venv with a requirements file or a modern project manager so dependencies are isolated and reproducible
• Package your application properly and run it as a module instead of executing internal files directly
• Use a containerised development environment so the interpreter and dependencies are consistent across machines

Pro tips

• When in doubt, run pip through Python rather than calling pip directly
• Keep a dependency file so a working environment can be recreated cleanly
• Avoid naming your own files after popular packages or standard library modules
• Test imports with a one-line script in the same environment before changing lots of code
• If a package documents a different import name from its install name, trust the package documentation

Safety notes

• Only install packages from sources you trust, especially on shared or production systems
• Be cautious when copying terminal commands from random websites, as package names can be maliciously similar to legitimate ones
• In production environments, follow your organisation's change control process before reinstalling packages or rebuilding environments

Cost considerations

Fixing the issue is often free if it only requires correcting the environment or import path. Costs mainly arise when a managed hosting setup, enterprise build pipeline, or external developer has to investigate and rebuild a broken environment.

Frequently asked questions

Sources & references

Guidance on this page is traced to documented sources. Last checked 25 September 2026.

• Python Standard Library Documentation - importlib · official

  Supports how Python's import system works and why ModuleNotFoundError relates to module discovery and import mechanisms.

• Python Packaging User Guide - Installing Packages · official

  Supports correct package installation practices and the distinction between environments when installing Python packages.

• Python Standard Library Documentation - venv · official

  Supports the explanation of isolated virtual environments and why packages installed in one environment are not available in another.

Related guides