Python ModuleNotFoundError: No module named 'X'
No module named 'X' — import fails
Verified against CPython 3.13 source (Lib/importlib/), Python docs: tutorial/modules, Stack Overflow #1471994 · Updated April 2026
> quick_fix
The package isn't installed in the Python interpreter you're running. Install it with pip (inside your activated virtualenv), or confirm you're running the right Python.
# 1. Check which Python you're using
which python
which pip
# 2. Install the missing package
pip install <package_name>
# 3. If still failing, install for this specific Python
python -m pip install <package_name>What causes this error
CPython searches sys.path for modules in order: current directory, PYTHONPATH entries, and the site-packages of the active interpreter. If the module is not in any of those locations, or if you installed it into a different interpreter (e.g., system Python vs virtualenv), the import fails with ModuleNotFoundError.
How to fix it
- 01
step 1
Confirm which Python and pip you're using
Run `which python` and `which pip`. Both should point to the same interpreter (same path prefix). If not, you installed the package for a different Python.
which python which pip python --version pip --version - 02
step 2
Install using the interpreter's pip
The safest install command is `python -m pip install <package>` — this guarantees pip runs for the same Python you're using.
python -m pip install requests - 03
step 3
Check your virtualenv is activated
If you're in a venv, your shell prompt should show `(venv)`. If it doesn't, activate with `source venv/bin/activate` (mac/Linux) or `venv\Scripts\activate` (Windows).
- 04
step 4
For local imports, check PYTHONPATH or add __init__.py
For your own modules, Python treats a folder as a package only if it contains an __init__.py file (or is on sys.path). For relative imports inside a package, use `from .module import x`.
Why ModuleNotFoundError happens at the runtime level
When Python encounters an import statement, the import system walks sys.path in order, querying each path entry's MetaPathFinder until one returns a ModuleSpec. Default finders check builtin modules, frozen modules, then PathFinder which scans every directory in sys.path for a matching .py, package __init__.py, or compiled .so/.pyd. If no finder returns a spec, ModuleNotFoundError is raised from importlib._bootstrap. sys.path is populated from the script directory, PYTHONPATH, and the active interpreter's site-packages, so the error is always 'this exact interpreter has no module named X on its sys.path right now.'
Common debug mistakes for ModuleNotFoundError
- Running pip install requests followed by python script.py and assuming the same Python, Homebrew, system, pyenv, conda, and Anaconda all install separate /usr/local/bin/pip shims that point at different interpreters.
- Activating a virtualenv but invoking the script with an absolute /usr/bin/python3 path, the activated PATH is bypassed and the system interpreter runs without the venv's site-packages.
- Adding the missing module's directory to sys.path at runtime via sys.path.append, works for the running script but breaks editor tooling, type checkers, and any subprocess that re-imports.
- Naming a local file the same as a standard-library module (e.g. random.py, types.py), the local file shadows the import and a downstream stdlib module fails to find a symbol it expected.
- Forgetting __init__.py in a package directory under Python 3.3+, implicit namespace packages partially work but break with explicit relative imports and editable installs.
When ModuleNotFoundError signals a deeper problem
Persistent ModuleNotFoundError signals the project has no enforced interpreter contract. When developers each pick their own Python via Homebrew, conda, or the OS, every machine resolves imports from a different sys.path and bug reports become unreproducible. The architectural fix is a tool like uv, Poetry, or Hatch that pins both the Python version and the resolved dependency set in one file the entire team commits. Combined with a .python-version file and a pre-commit check that aborts if the interpreter mismatches, this kills the error class permanently. Without it, you get 'works on my machine' compounding across every new contributor.
Editor's take
This error has a particular talent for surfacing at exactly the wrong moment: a startup's CI pipeline passes because the build container has the package baked in from a stale Docker layer, but the fresh production deploy — triggered 20 minutes before a demo — fails on cold startup because no one pinned the dependency in requirements.txt. In a small team running a FastAPI monolith on Railway or Fly.io, there's no platform team to catch the drift between what's installed locally and what's in the image. The on-call engineer is also the original developer, and the postmortem is a Slack thread.
Hitting this error and knowing exactly why it happened — not just running pip install, but checking which Python sys.executable is active, auditing pip show versus pip list, and then locking it in pyproject.toml with a [tool.uv.sources] entry or a pinned requirements layer — is roughly a first-to-third month transition marker. The engineer who fixes it by running pip install and moving on will see it again in six weeks. The engineer who follows up with python -m pip install (to guarantee interpreter alignment) and adds a pre-commit check against requirements drift has understood something durable about Python's environment model.
Debugging this usually reveals a cluster: ImportError for a submodule (when the package installed but the namespace changed between major versions), AttributeError immediately after a successful import (package present but wrong version, missing a method added in 2.x), and subprocess.CalledProcessError wrapping a pip install --require-virtualenv call that failed silently in a CI step. Check your PYTHONPATH and VIRTUAL_ENV env vars — one of them is almost always wrong or absent.
By Bikram Nath · Curator · Updated April 2026
Frequently asked questions
Why does pip install work but the import still fails?
Because pip and python are pointing at different interpreters. Use `python -m pip install <package>` to force the same Python.
How do I install a package just for this project?
Create a virtualenv: `python -m venv .venv && source .venv/bin/activate && pip install <package>`. The virtualenv's Python has its own site-packages.
ModuleNotFoundError vs ImportError — what's the difference?
ModuleNotFoundError is a subclass of ImportError introduced in Python 3.6. It specifically means the module itself was not found. ImportError can also fire if the module exists but a specific name isn't in it.