エラーの内容
VS Code で F5 を押して Python デバッグセッションを開始すると、デバッグコンソールに次のメッセージが表示されます：
ModuleNotFoundError: No module named 'debugpy'
セッションは即座に終了します。ブレークポイントも出力も何もなく、ただその一行だけが表示されます。
原因
debugpy は VS Code が Python プロセスに注入するデバッグアダプターです。Python 拡張機能にバンドルされて同梱されていますが、VS Code はあなたのインタープリター内でそれを実行します。そのインタープリターが debugpy にアクセスできない場合、インポートが失敗します。新しく作成した仮想環境、conda 環境、および VS Code が一度も触れたことのないシステム Python のインストールが主な原因として挙げられます。
ほとんどの場合、原因は次の 2 つのいずれかです：
- VS Code が
debugpyをインストールしていない仮想環境を参照している。 - 最近仮想環境を再作成したが、開発用の依存関係を再インストールするのを忘れた。
修正方法 1 — アクティブな環境に debugpy をインストールする
まず、VS Code が実際に使用している Python を確認します。コマンドパレット（Ctrl+Shift+P / Cmd+Shift+P）を開き、Python: Select Interpreter を実行して、パスを確認してください。プロジェクトの仮想環境を指している必要があります。
次に、その特定のインタープリターに debugpy をインストールします：
# ターミナルで仮想環境をアクティブにした状態で：
pip install debugpy
# またはインタープリターを明示的に指定する場合：
/path/to/your/venv/bin/python -m pip install debugpy
# Windows の場合：
.\venv\Scripts\python.exe -m pip install debugpy
デバッグセッションを再起動してください。ほとんどの場合、これで解決します。
修正方法 2 — VS Code が正しいインタープリターを参照するようにする
debugpy はインストールされているのにエラーが続く場合、VS Code が誤った Python を使用している可能性があります。複数の環境がある場合、プロジェクトの仮想環境ではなくシステム Python がデフォルトになってしまうことがあります。
- コマンドパレットを開き、Python: Select Interpreter を選択します。
- 仮想環境内のインタープリターを選択します。
./venv/bin/pythonや./.venv/bin/python3のようなパスを探してください。 - 一覧に表示されない場合は、Enter interpreter path をクリックして手動で参照してください。
.vscode/settings.json でワークスペースごとに固定します：
{
"python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python"
}
修正方法 3 — プロジェクトの依存関係に debugpy を追加する
CI、Docker、またはチーム共有の環境で新しい仮想環境を使用する場合は、debugpy を開発用の依存関係に最初から追加しておくことで、今後抜け漏れを防げます：
# requirements-dev.txt
debugpy>=1.8.0
pip install -r requirements-dev.txt
代わりに pyproject.toml を使用する場合：
[project.optional-dependencies]
dev = ["debugpy>=1.8.0"]
pip install -e ".[dev]"
修正方法 4 — launch.json の設定を確認する
カスタムの .vscode/launch.json を使用している場合は、Python のパスが上書きされていたり、予期しないインタープリターを指定していないか確認してください：
{
"version": "0.2.0",
"configurations": [
{
"name": "Python: Current File",
"type": "debugpy",
"request": "launch",
"program": "${file}",
"console": "integratedTerminal"
}
]
}
古い設定では "type": "python" が使われていますが、それでも問題なく動作します。いずれにしても、type フィールドがこのエラーの原因になることはありません。
修正方法 5 — conda 環境の場合
conda では、アクティブ化した環境内で通常の pip が問題なく動作します。conda ネイティブのオプションもあります：
conda activate myenv
pip install debugpy
# または
conda install -c conda-forge debugpy
VS Code で選択されているインタープリターが conda 環境内（例：/home/user/miniconda3/envs/myenv/bin/python）を指しており、ベースの Python ではないことを確認してください。これが conda 特有のよくあるミスです。
修正の確認
F5 を押す前に、VS Code の統合ターミナルで次のコマンドを実行してください：
python -c "import debugpy; print(debugpy.__version__)"
1.8.14 のようなバージョン番号が表示されるはずです。まだ ModuleNotFoundError が出る場合は、ターミナルも別の Python を使用しています。インタープリターの選択に戻って再確認してください。
インポートが成功したら、F5 を押してください。ブレークポイントがバインドされ、デバッグコンソールにプログラムの出力が表示され、debugpy は邪魔をしなくなります。
予防策
debugpy>=1.8.0を記載したrequirements-dev.txtをコミットしておく — 新しくクローンしたときに自動的にインストールされます。.vscode/settings.jsonにpython.defaultInterpreterPathを設定し、リポジトリにコミットしておく。チーム全員が初日から正しいインタープリターを使用できます。- 仮想環境を再作成した後は、VS Code を開く前に
pip install -r requirements-dev.txtを実行してください。VS Code がプロンプトを表示するまで待たないでください。表示されません。