ModuleNotFoundError: Fix Python Imports That Fail

You installed the package — you watched pip succeed — and Python still says it doesn't exist. ModuleNotFoundError: No module named 'requests' is the interpreter telling you it searched every directory it knows and found nothing by that name. The search list is sys.path: the script's folder, PYTHONPATH entries, and the environment's site-packages. When any link in that chain points somewhere unexpected, the import fails no matter how correctly you spelled it. This error fires in five familiar situations: pip installed into one interpreter while the app runs under another, a script launched as python pkg/mod.py instead of python -m pkg.mod so the package root never lands on the path, a PYTHONPATH that exists on your laptop but not the server, a local random.py or email.py shadowing the standard library, and a package missing its __init__.py on tooling that still expects one. Each shape has a one-command confirmation — which python3, python -m pip show, printing sys.path or a module's __file__ — and a permanent fix that stops it recurring. This article walks through the lookup mechanism, the interpreter-mismatch trap, the -m package context, stdlib shadowing, namespace packages, and how this error differs from its parent ImportError.

sys.path Missed: Where Python Looked Before Giving Up

Every import starts with a search, and sys.path is the list of places Python agrees to look. In order: the launching context (sys.path[0], covered in the -m section), entries from the PYTHONPATH environment variable, the standard library, and the current environment's site-packages. The import system asks each location's finder for the top-level module name, takes the first hit, and only when every finder declines does it raise ModuleNotFoundError — carrying the missing name on exc.name so your handler can read it programmatically. That search order explains most mysteries. The same import requests succeeds in one terminal and fails in another because the two interpreters own different site-packages folders, or because one launch put the project root on the path and the other didn't. Your first diagnostic is always a dump from inside the failing context: python3 -c "import sys, pprint; pprint.pp(sys.path)" shows exactly which shelves the librarian checked. Compare that against where the package actually lives (python3 -m pip show <pkg> prints Location:), and the gap — wrong environment, missing root, absent PYTHONPATH — is usually visible in seconds rather than hours.

import sys

print("interpreter:", sys.executable)
print("entry 0:", sys.path[0])
print("search list:")
for p in sys.path[:4]:
    print(" -", p)

try:
    import _definitely_missing_module_xyz
except ModuleNotFoundError as exc:
    print("missing name:", repr(exc.name))
    print("message:", exc)

pip Installed It, Python Can't See It: The Interpreter Mismatch

The single most common cause of this error is also the most embarrassing: the package is installed, just not for the interpreter running your code. pip is not a universal installer — it's a script pinned to one specific Python. On a machine with a system Python, a Homebrew Python, and two virtual environments, pip, pip3, and python3 can easily belong to three different worlds. pip install requests succeeding while python3 -c "import requests" fails is the signature symptom, and it confuses people because both commands look authoritative. The fix is a habit change: never address pip directly. python3 -m pip install requests runs pip as a module inside that exact interpreter, so installer and importer cannot disagree. Diagnose the current mess with which -a python3 pip pip3 (multiple lines means multiple worlds) and python3 -m pip show <pkg> versus pip show <pkg> — when the two answers differ, you've found your split. Virtual environments sharpen the trap because an inactive venv leaves your shell on the system Python while your service file points at the venv, or vice versa. Spell the interpreter absolutely everywhere it matters: Dockerfiles, systemd units, cron lines.

import sys
import site

print("executable:", sys.executable)
print("prefix:", sys.prefix)
print("site-packages:", site.getsitepackages()[0])
print("pair me with: python -m pip")

Script vs -m: The Package Context That Makes Imports Work

How you launch the code rewrites the search list, which is why imports that work in the IDE die in production. Running python3 pkg/mod.py sets sys.path[0] to the pkg/ folder itself and leaves __package__ unset — the module has no idea it lives inside a package, so from pkg import helpers and any explicit relative import like from . import helpers both fail with ModuleNotFoundError. Running python3 -m pkg.mod from the project root instead sets sys.path[0] to the root directory and fills in __package__, so absolute and relative imports resolve exactly as the package author intended. IDEs hide this because they silently add the project root to the path before running, matching -m behavior without telling you. The rule for teams: pick one launch command, write it in the README, and use the identical command in systemd units, Docker CMDs, and CI steps. When a traceback shows No module named 'pkg' for your own top-level folder, don't reinstall anything — print sys.path[0], confirm it points at the script's folder instead of the root, and switch the launch to -m. Nine times out of ten that's the entire incident. A quick proof settles any debate: run the entry both ways from the project root and print sys.path[0] each time. The script form shows the package folder; the -m form shows the root. That one-line difference is the whole incident.

print("__name__:", __name__)
print("__package__:", __package__)

import sys
print("entry 0:", sys.path[0])
print("run me as: python -m pkg.mod from the root")

A Local File Named random.py: Shadowing the Standard Library

The cruelest variant of this error isn't a missing module — it's the wrong module winning the race. Your script's own directory sits ahead of the standard library and site-packages on sys.path, so a local file named random.py, email.py, or json.py hijacks every import random in the process, including imports inside third-party libraries you didn't write. The symptoms feel haunted: random.randint suddenly doesn't exist, smtplib breaks with bizarre attribute errors, and the traceback points at your innocent utility file. New projects trip on test.py and requests.py too — the latter shadows the real HTTP library the moment someone adds it as a dependency. Diagnosis takes one line: python3 -c "import random; print(random.__file__)" shows exactly which file won. If the path points into your project, rename the shadow immediately (app_random.py, mailer.py) and purge bytecode caches, because a stale __pycache__/random.cpython-*.pyc can keep serving the shadow after the rename. Prevention belongs in CI: a lint step that fails the build when any top-level .py filename collides with the standard library list catches this before it ever ships. When the culprit file is found, check its git history too -- shadows often arrive as quick debug scripts that were never meant to be committed, and the fix includes deleting them outright.

import random

print("random loads from:", random.__file__)
print("stdlib copy:", "site-packages" not in random.__file__)
print("randint works:", random.randint(1, 6))

__init__.py or Not: Regular vs Namespace Packages

Packages come in two flavors, and the missing __init__.py only breaks one of them. A regular package is a folder with an __init__.py (even an empty one) that marks the directory as importable and runs first on import — the place for package-level setup. Delete that file and older tooling, installers, and some test runners stop seeing the folder as a package, producing ModuleNotFoundError for code that sits right there on disk. The fix is trivial: restore the file. Python 3 also supports namespace packages: folders without __init__.py whose portions across several sys.path entries merge into one logical package. That design serves split distributions (plugins, large frameworks), not everyday apps — reaching for it accidentally, by deleting init files or half-installing a project, buys confusing behavior where some submodules resolve and others don't. When your own package won't import, inspect the layout directly: ls pkg/__init__.py plus python3 -c "import pkg; print(pkg.__path__)" shows whether the package resolved and which directories contributed. For application code the policy is simple: every package folder keeps its __init__.py, and namespace mechanics stay a conscious choice, not an accident.

import json

print("module file:", json.__file__)
print("is a package:", hasattr(json, "__path__"))
print("search locations:", list(json.__path__)[:2])

ModuleNotFoundError vs ImportError: Subclass, Circles, Broken Code

ModuleNotFoundError is a subclass of ImportError, and the distinction decides what your except clauses mean. The child fires in exactly one situation: the import system found no module by that name anywhere on sys.path. The parent covers everything else that can go wrong around imports — a circular import where module A needs B while B is still initializing A (surfacing as ImportError: cannot import name ... from partially initialized module), a found module that raises during its own execution, or from pkg import missing_name where the package exists but the name inside it doesn't. Conflating them causes real incidents: a broad except ImportError around an optional dependency swallows a circular-import failure and reports "package not installed," sending the team to reinstall what was never missing while the true cycle hides. The discipline is narrow catching — except ModuleNotFoundError for the optional-dependency fallback, and let genuine ImportErrors crash loudly so the cycle or the broken module gets fixed. Read the message shape too: No module named 'x' (child, absent) versus cannot import name 'y' from 'x' (parent, present-but-broken) point at opposite fixes.

print("subclass:", issubclass(ModuleNotFoundError, ImportError))

try:
    import _missing_mod_abc_xyz
except ImportError as exc:
    print("caught as:", type(exc).__name__)
    print("message:", exc)