Fix ModuleNotFoundError in VS Code: 5 Causes and Fixes

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

The error is almost never about a missing package. It is almost always about which Python is running your code.

Step 1: Check Which Python VS Code Is Using#

Open Command Palette (Ctrl+Shift+P on Windows/Linux, Cmd+Shift+P on Mac) and run 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 any system Python instead of .venv/bin/python, that is 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 the Package Is Installed in the Right Environment#

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

# Check if the 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 will not find it. Always activate before installing.

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

If the error is about your own code and not a third-party package, the directory is probably not set up as a Python package:

project/
├── main.py
└── utils/
    └── helpers.py

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

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

Step 4: Check for Editable Install Issues#

If you are 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 do not 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:

{
  "python.defaultInterpreterPath": "/usr/bin/python3"
}

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

Diagnostic Checklist#

Run these in order before changing anything else:

# 1. Which Python is active?
which python

# 2. Is the venv active?
echo $VIRTUAL_ENV

# 3. Is the package installed in this 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 Causes#

FAQ#

Q: Why does the correct interpreter show in the status bar but the error still appears?

A: VS Code may have cached the old interpreter. Reload the window with Ctrl+Shift+P then Developer: Reload Window and try again.

Q: I have multiple venvs in the same project. Which one should I pick?

A: The one where you installed your dependencies. Run pip list inside each to check. If you are unsure, delete them and create a fresh one at the project root.

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