ix ModuleNotFoundError in VS Code — 5 Causes and Fixes

What's Actually Happening#

VS Code runs Python through a specific interpreter. If that interpreter isn't your virtual environment — or the package isn't installed in it — you get ModuleNotFoundError even when pip install looked like it worked.

Step 1: Check Which Python VS Code Is Using#

Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → Python: Select Interpreter.

The interpreter shown in the bottom status bar is what VS Code uses to run your files. If it shows /usr/bin/python3 or a system Python instead of .venv/bin/python, that's the problem.

Fix: Select the interpreter that points to your virtual environment. Look for one with .venv or venv in the path.

# Confirm which Python your terminal is using
which python
python --version

Step 2: Verify Package Is Installed in the Right Environment#

# Activate your venv first
source .venv/bin/activate      # Linux/Mac
.venv\Scripts\activate         # Windows

# Check if package is installed
pip show requests

# If not installed
pip install requests

# Verify it worked
python -c "import requests; print(requests.__version__)"

Warning: Running pip install without activating the venv installs into your system Python. VS Code's venv interpreter won't find it. Always activate before installing.

Step 3: Fix Missing __init__.py for Local Modules#

If the ModuleNotFoundError is about your own code (not a third-party package):

project/
├── main.py
└── utils/
    └── helpers.py   # ← missing __init__.py

# main.py
from utils.helpers import format_date  # ModuleNotFoundError: No module named 'utils'

Fix: Add __init__.py to make utils/ a proper Python package.

touch utils/__init__.py

Then run from the project root, not from inside a subdirectory:

cd project/
python main.py   # ✅ works

Step 4: Check for Editable Install Issues#

If you're developing a package and importing it by name:

# Install your own package in editable mode
pip install -e .

# Verify
pip show your-package-name

Without -e, changes to your source files don't reflect in the installed package. With -e, Python imports directly from your source directory.

Step 5: VS Code Settings Override#

Sometimes VS Code has a python.defaultInterpreterPath hardcoded in .vscode/settings.json that overrides your selection:

// .vscode/settings.json — check for this
{
  "python.defaultInterpreterPath": "/usr/bin/python3"  // ← wrong
}

Fix: Update the path to your venv, or delete the setting and use Command Palette to select the interpreter.

Diagnostic Checklist#

# 1. Which Python?
which python

# 2. Venv active?
echo $VIRTUAL_ENV

# 3. Package installed in active env?
pip show <package-name>

# 4. What does Python see in sys.path?
python -c "import sys; print('\n'.join(sys.path))"

# 5. Can Python import it at all?
python -c "import <package>"

Common Cause Summary#

For ModuleNotFoundError in complex monorepos or projects with custom package structure, paste the full error and your directory tree into DebugAI. It identifies whether the problem is interpreter mismatch, missing package, or broken import path.