Introduction

ImportError or ModuleNotFoundError usually means Python could not find the module where it expected to. The fix is not always “install the package.” The real cause may be the active interpreter, the current working directory, the package layout, or the way the script was launched.

Check Which Python You Are Running

Start by confirming the interpreter and environment actually executing the script.

python --version
which python
python -m pip --version

Those commands tell you whether pip is installing into the same interpreter that runs the script. A very common failure mode is installing a package into one virtual environment and executing the script with another Python binary.

Confirm the Module Is Installed

If the missing import is a third-party package, check whether it exists in the current environment.

python -m pip show requests
python -m pip list | grep requests

If nothing appears, install it with the same interpreter:

python -m pip install requests

Using python -m pip is safer than calling pip directly because it ties installation to the interpreter you chose.

Understand How Python Builds sys.path

Python searches imports using sys.path. That includes the script directory, standard library locations, and installed site-packages directories.

1import sys
2
3for path in sys.path:
4    print(path)

If your project package is not on that list, Python will not find it. That often happens when a script is launched from the wrong directory or when package code is run as a loose file instead of as a module.

Prefer python -m for Package Code

Suppose your project looks like this:

1project/
2    app/
3        __init__.py
4        main.py
5        utils.py

If main.py imports app.utils, running the file directly from inside app can break imports. Instead, run it from the project root:

python -m app.main

That tells Python to treat app as a package and build the import path correctly.

Watch for Naming Conflicts

Local filenames can shadow installed packages or standard-library modules. For example, if your file is named requests.py, then this import becomes confusing:

import requests

Python may import your local file instead of the external package. Similar issues happen with names such as json.py, typing.py, or random.py. Rename the conflicting file and remove any leftover __pycache__ directories if necessary.

Relative Imports Require Package Context

Inside package code, relative imports work only when Python knows the package context.

from .utils import format_name

If you run that file directly as a script, Python does not treat it as part of a package, so the relative import fails. Again, the fix is usually to run the package entry point with python -m package.module.

Virtual Environments Solve Many Cases

A clean virtual environment reduces ambiguity.

1python -m venv .venv
2source .venv/bin/activate
3python -m pip install -r requirements.txt
4python -m app.main

That makes the interpreter, installed packages, and project dependencies much more predictable.

A Practical Debug Checklist

When an import fails, this short script is often enough to reveal the problem.

1import sys
2import os
3
4print("executable:", sys.executable)
5print("cwd:", os.getcwd())
6print("path entries:")
7for item in sys.path:
8    print(" ", item)

Run it with the same command that triggers the error. You will usually spot either the wrong interpreter or a missing project path immediately.

Common Pitfalls

The most common mistake is installing a package with one interpreter and running the script with another. Another is launching a file inside a package directly instead of using python -m. Developers also frequently shadow real packages with local filenames such as requests.py. Finally, adding random paths to sys.path can hide the real packaging problem instead of fixing it cleanly.

Summary

• Verify the exact Python interpreter running the script.
• Install packages with python -m pip to match that interpreter.
• Inspect sys.path when Python cannot find local project modules.
• Run package code with python -m package.module.
• Avoid local filenames that shadow standard or third-party modules.