VSCodeでPythonのデバッグが動かない原因と対処法｜launch.jsonエラーの解決手順

① 結論

結論：VSCodeでPythonのデバッグが動かない原因の多くは、実行に使っているPythonインタープリタと、デバッグ設定（launch.json）が一致していないことです。特に「venv未選択」「launch.jsonのprogram/console設定ミス」「debugpyが入っていない」ケースが頻発します。Python: Select Interpreter と python -m debugpy を基準に切り分ければ解決できます。

② 症状

  • F5を押してもデバッグが開始されない
  • 「No module named debugpy」「Debug adapter process has terminated」などのエラー
  • 通常実行はできるが、デバッグ実行だけ失敗する
  • 別プロジェクトでは動くが、このフォルダだけ動かない

③ 原因（最大3つ）

原因①：選択されているPythonインタープリタが誤っている

【詳細】
VSCodeのデバッグは、ワークスペースで選択されているPythonインタープリタを使って実行されます。venvを作成していても、別のPython（システムPythonなど）が選択されていると、依存関係やdebugpyが見つからずデバッグに失敗します。
起きやすい条件：venv作成後に未選択／フォルダをコピーした／WSL/Remote切替後
判断ポイント：

which python
python -c "import sys; print(sys.executable)"

想定の venv/bin/python を指していなければ不一致です。

原因②：launch.jsonの設定ミス（program / console / cwd）

【詳細】
launch.json の program が実行したいファイルを指していない、cwd がズレている、console が環境に合っていないと、デバッグ開始時にエラーになります。特に複数階層のプロジェクトやWSL環境で起きやすいです。
起きやすい条件：Monorepo構成／相対パスの誤指定／WSL＋Windows混在
判断ポイント：

{
  "program": "${file}",
  "cwd": "${workspaceFolder}"
}

が設定されているか確認します。

原因③：debugpyが実行環境にインストールされていない

【詳細】
VSCodeのPythonデバッグは内部で debugpy を使用します。インタープリタにdebugpyが入っていない、または別環境に入っていると、デバッグ開始時に失敗します。
起きやすい条件：venv作成直後／pip実行環境のズレ／sudo pip使用歴あり
判断ポイント：

python -m pip show debugpy

表示されなければ未導入です。

④ 切り分け手順（コマンド付き）

  1. VSCodeでインタープリタを選択：
  2. Python: Select Interpreter
  3. 実行Pythonの確認：
  4. which python
  5. python --version
  6. debugpyの有無確認：
  7. python -m pip show debugpy
  8. launch.jsonの確認：
  9. .vscode/launch.json

⑤ 解決方法

解決策①：正しいインタープリタを選択・固定

venvを使う場合は、プロジェクト直下で作成し、必ず選択します。

python -m venv venv
source venv/bin/activate

解決策②：debugpyを実行環境にインストール

python -m pip install --upgrade debugpy

解決策③：最小構成のlaunch.jsonに戻す

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

⑥ 再発防止

  • プロジェクトごとにvenvを作成し、インタープリタを固定する
  • pipは python -m pip で実行する
  • launch.jsonは最小構成から追加していく

⑦ それでもダメな場合

  • 新規フォルダで最小スクリプト＋venv＋デバッグを試し、プロジェクト固有か切り分ける
print("debug ok")
  • VSCodeの「Output」→「Python」ログを確認し、具体的な失敗理由を特定する

コメント

タイトルとURLをコピーしました