Introduction

Python finds modules by searching sys.path, which is built from the Python installation location, PYTHONPATH, and .pth files. When pip install uses one Python interpreter but the script runs with another, installed packages are invisible. This is the most common cause of ModuleNotFoundError in environments with multiple Python installations.

Symptoms

  • ModuleNotFoundError: No module named 'flask' even though pip list shows Flask installed
  • pip install flask reports "Requirement already satisfied" but import still fails
  • Different Python interpreters on the same system
  • VS Code or PyCharm uses a different interpreter than the terminal

```bash $ python myapp.py ModuleNotFoundError: No module named 'requests'

$ pip list | grep requests requests 2.31.0

$ which python /usr/bin/python $ which pip /home/user/.local/bin/pip # Different Python installations! ```

Common Causes

  • pip and python pointing to different installations
  • System Python vs Homebrew Python vs pyenv Python
  • Global pip used but virtual environment activated
  • IDE using a different interpreter than terminal
  • Multiple Python versions installed (3.9, 3.10, 3.11, etc.)

Step-by-Step Fix

  1. 1.Diagnose which Python and pip are being used:
  2. 2.```bash
  3. 3.python -c "import sys; print(sys.executable)"
  4. 4.python -c "import sys; print(sys.path)"

pip --version # Shows: pip 24.0 from /home/user/.local/lib/python3.11/... (python 3.11)

# Check if they match: python -m pip --version # This shows pip for the ACTIVE Python interpreter ```

  1. 1.Always use python -m pip instead of bare pip:
  2. 2.```bash
  3. 3.# WRONG - may use different Python
  4. 4.pip install requests

# CORRECT - guaranteed to use the same Python python -m pip install requests python3.11 -m pip install requests ```

  1. 1.Activate the correct virtual environment:
  2. 2.```bash
  3. 3.# Check if in virtual environment
  4. 4.python -c "import sys; print(sys.prefix)"
  5. 5.python -c "import sys; print(sys.base_prefix)"

# If prefix == base_prefix, NOT in venv # Activate the correct environment: source /path/to/venv/bin/activate

# Verify which python # Should show venv path ```

  1. 1.Fix IDE interpreter selection:
  2. 2.```bash
  3. 3.# VS Code: Ctrl+Shift+P -> "Python: Select Interpreter"
  4. 4.# Or in .vscode/settings.json:
  5. 5.# {
  6. 6.# "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
  7. 7.# }

# PyCharm: Settings -> Project -> Python Interpreter ```

  1. 1.Use PYTHONPATH as a workaround (not recommended long-term):
  2. 2.```bash
  3. 3.# Find where packages are installed
  4. 4.python -m pip show flask | grep Location
  5. 5.# Location: /home/user/.local/lib/python3.11/site-packages

# Add to path temporarily export PYTHONPATH="/home/user/.local/lib/python3.11/site-packages:$PYTHONPATH"

# Or add at runtime (before other imports) import sys sys.path.insert(0, '/home/user/.local/lib/python3.11/site-packages') ```

Prevention

  • Always use python -m pip instead of pip directly
  • Create and activate virtual environments per project
  • Use pyenv to manage multiple Python versions
  • Pin Python version in pyproject.toml: requires-python = ">=3.11"
  • Use poetry or uv which manage interpreter and packages together
  • Add interpreter check to scripts:
  • ```python
  • import sys
  • expected_prefix = "/home/user/project/.venv"
  • if not sys.prefix.startswith(expected_prefix):
  • print(f"WARNING: Running with {sys.executable}, expected {expected_prefix}")
  • sys.exit(1)
  • `