Fix 'ModuleNotFoundError: No module named debugpy' in VS Code Python Debug

The Error

You press F5 in VS Code to start a Python debug session and get this in the Debug Console:

ModuleNotFoundError: No module named 'debugpy'

The session dies immediately. No breakpoints, no output — just that one line.

Root Cause

debugpy is the debug adapter VS Code injects into your Python process. It ships bundled with the Python extension — but VS Code runs it inside your interpreter. If that interpreter doesn't have debugpy accessible, the import fails. Fresh virtualenvs, conda environments, and system Python installs VS Code has never touched are the usual suspects.

Nine times out of ten, it's one of these two:

• VS Code is pointing at a virtualenv that doesn't have debugpy installed.
• You recreated the virtualenv recently and forgot to reinstall dev dependencies.

Fix 1 — Install debugpy in the Active Environment

Start by confirming which Python VS Code is actually using. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P), run Python: Select Interpreter, and note the path — it should point to your project's virtualenv.

Now install debugpy into that exact interpreter:

# With the virtualenv active in the terminal:
pip install debugpy

# Or target the interpreter explicitly:
/path/to/your/venv/bin/python -m pip install debugpy

# Windows:
.\venv\Scripts\python.exe -m pip install debugpy

Restart the debug session. This resolves it the vast majority of the time.

Fix 2 — Point VS Code to the Right Interpreter

debugpy is installed but the error persists? VS Code is probably using the wrong Python. With multiple environments around, it can default to system Python instead of your project's venv.

• Open Command Palette → Python: Select Interpreter.
• Pick the interpreter inside your virtualenv — look for paths like ./venv/bin/python or ./.venv/bin/python3.
• Don't see it listed? Click Enter interpreter path and browse to it manually.

Lock it in per-workspace via .vscode/settings.json:

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

Fix 3 — Add debugpy to Your Project Dependencies

Working with fresh virtualenvs in CI, Docker, or shared team setups? Add debugpy to your dev requirements upfront so it never gets left out again:

# requirements-dev.txt
debugpy>=1.8.0

pip install -r requirements-dev.txt

Using pyproject.toml instead:

[project.optional-dependencies]
dev = ["debugpy>=1.8.0"]

pip install -e ".[dev]"

Fix 4 — Check the launch.json Configuration

Got a custom .vscode/launch.json? Check that it isn't overriding the Python path or pointing to an unexpected interpreter:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal"
    }
  ]
}

Older configs use "type": "python" — that still works fine. The type field isn't what triggers this error either way.

Fix 5 — conda Environments

On conda, standard pip works fine inside an activated environment. There's also a conda-native option:

conda activate myenv
pip install debugpy
# or
conda install -c conda-forge debugpy

Double-check that VS Code's selected interpreter points into the conda env (e.g., /home/user/miniconda3/envs/myenv/bin/python), not the base Python. That's the most common conda-specific mistake here.

Verify the Fix

Before hitting F5, run this in VS Code's integrated terminal:

python -c "import debugpy; print(debugpy.__version__)"

You should see a version number like 1.8.14. Still getting ModuleNotFoundError? The terminal is also using a different Python — go back and recheck interpreter selection.

Once that import works, press F5. Breakpoints bind, the Debug Console shows your program output, and debugpy gets out of your way.

Prevention

• Commit a requirements-dev.txt with debugpy>=1.8.0 — any new clone installs it automatically.
• Set python.defaultInterpreterPath in .vscode/settings.json and commit it to the repo. The whole team lands on the right interpreter from day one.
• After recreating a virtualenv, run pip install -r requirements-dev.txt before opening VS Code. Don't wait for VS Code to prompt you — it won't.