Fix ModuleNotFoundError / ImportError in 5 Minutes — Cause-by-Cause Diagnostic Table and Copy-Paste Commands

Fix ModuleNotFoundError / ImportError in 5 Minutes — Cause-by-Cause Diagnostic Table and Copy-Paste Commands

Python Development Guide, Part 2 · If you set up the environment in Part 1 but got a wall of red text when you ran python app.py, this post is for you.

"I definitely ran pip install — why am I still getting No module named?"

In Part 1 you created a venv and installed packages. Then you ran the app and got this:

ModuleNotFoundError: No module named 'requests'

When a package is installed but still not found, the reason is almost always that the Python you installed into is not the Python you are running. The good news: import errors look infinite, but they collapse into exactly 7 causes.

1. Never actually installed
2. Wrong interpreter / venv not activated
3. sys.path · PYTHONPATH issues
4. Relative import errors
5. Package name ≠ import name
6. Circular import
7. Missing __init__.py

The goal of this post is to kill the guessing. Narrow the cause with diagnostic commands → look it up in the table → fix it with copy-paste.

30-second diagnostic routine: 4 commands that narrow the cause

When you are stuck, run these from top to bottom as-is. In 30 seconds you will see which Python is looking at which packages.

# 1) Which executable is 'python' actually pointing to
which python        # Windows: where python

# 2) Which Python is 'pip' attached to
pip -V

# 3) The running Python and the full module search path
python -c "import sys; print(sys.executable); print(sys.path)"

# 4) Packages actually installed for that Python
python -m pip list

How you read each line is the key.

Remember one core rule: use python -m pip install, not pip install. That installs into "this Python, right now." PEP has long settled on python -m as the recommended pattern.

Diagnostic table by cause and copy-paste fixes

With those diagnostic results in hand, find your symptom in the table below.

Practical tip: Most import errors that blow up in real work converge on cause ② (interpreter mismatch) alone. If it works in the terminal but breaks only in the IDE, that is almost certainly it. So when you get stuck, print sys.executable before you start theorizing.

Three traps that blow up constantly

① IDE interpreter mismatch (VS Code / PyCharm)

If it works in the terminal but the IDE Run button breaks it, the IDE is using a different Python than the venv.

VS Code

1. Ctrl/Cmd + Shift + P → Python: Select Interpreter
2. Pick the project venv path (./venv/bin/python) from the list
3. To pin it, set it directly in .vscode/settings.json:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python"
}

(Screenshot caption: Check that the interpreter path in the VS Code status bar at the bottom right points at the venv)

PyCharm

1. Settings → Project → Python Interpreter
2. Gear icon → Add Interpreter → Add Local Interpreter
3. Choose Existing and point it at venv/bin/python

(Screenshot caption: The project venv selected in the Python Interpreter dropdown)

② Package name ≠ import name cheat sheet

Some packages have a different name for pip install than for import. If you do not know this, you will swear you installed it and still get No module named.

Rule of thumb: hyphens become underscores on import, or the name changes entirely. When in doubt, check the real package info with python -m pip show pillow.

③ python script.py vs python -m package.module

99% of relative import (from . import utils) errors come from how you run the file.

# ❌ Running a file that uses relative imports directly will break
python myapp/main.py
# → attempted relative import with no known parent package

# ✅ Running it as a package gives it a parent-package context so it works
python -m myapp.main

With -m, Python treats the module as "part of a package," which is what relative imports need.

2026 trend: Astral's uv is quickly becoming the standard, and more teams are using uv pip install / uv run. uv run python ... auto-picks the project venv, so the cause ② mismatch problem almost disappears. Even on Python 3.13, a per-project venv plus running with python -m is still the safest default.

Wrap-up: finish it with one diagnostic table

When you get stuck, the order is always the same.

1. Check that which python and pip -V paths match → if not, activate the venv
2. Check that the package is in python -m pip list → if not, python -m pip install
3. If it is there and still fails → check the import-name cheat sheet and relative imports (-m execution)

Follow just these 3 steps from the top and import errors resolve in 5 minutes.

References: official docs

The primary sources for the behavior, settings, and errors covered here are the official docs below. Check them for version-specific options and exact behavior.

• Python documentation

Frequently asked questions (FAQ)

Q. It works in the terminal but I get No module named only in Jupyter (.ipynb). A. The notebook kernel is using a different Python. In a cell, run import sys; print(sys.executable) to see the kernel path. Even if you run !pip install inside the notebook, it can install into the wrong Python, not the kernel — use %pip install X (magic command) instead, or register the venv as a kernel:

python -m ipykernel install --user --name=myvenv

Then select the myvenv kernel in Jupyter.

Q. The module is missing only inside a Docker container. A. Check three things. ① Is the order COPY requirements.txt → RUN pip install correct (copy requirements before the full source so the build cache actually helps), ② Did you change dependencies but RUN pip install never re-ran because of cache (docker build --no-cache to verify), ③ Did the base image Python version differ from local so an incompatible wheel got installed. The fastest check is to run python -m pip list inside the container and see what is actually installed.

Q. pip install succeeded but at runtime it says the module is missing. A. Classic case: you installed into the user site (pip install --user) but you are running system Python. Compare pip -V and which python paths, and always install with python -m pip install so it goes into "this Python, right now."

In the next post (Part 3) we cover Python debugging and exception handling in practice — how to read a traceback fast, plus using pdb / breakpoint().