【Python×VSCode】Pythonをローカルでデバッグする方法

pythonではデバッグを行う場合

• debugpy

を使って実行するのが第一選択肢にになる

そしてpythonの「debugpy」を使ったデバッグ構成パターンは

Copy
Python実行場所
├─ ローカル
│  └─ デバッグ操作位置：同一環境
│     ├─ デバッグ方式：launch
│     └─ デバッグ方式：attach
│        ├─ debugpy起動形態：埋め込み（import debugpy）
│        └─ debugpy起動形態：外部起動（python -m debugpy）
│
└─ コンテナ
   ├─ デバッグ操作位置：同一環境（コンテナに入る）
   │  ├─ デバッグ方式：launch
   │  └─ デバッグ方式：attach
   │     ├─ debugpy起動形態：埋め込み
   │     └─ debugpy起動形態：外部起動
   │
   └─ デバッグ操作位置：別環境（ホストから接続）
      └─ デバッグ方式：attach
         ├─ debugpy起動形態：埋め込み
         └─ debugpy起動形態：外部起動

がある。
詳しくは下記記事参照

【Python】デバッグの仕組みを理解する(debugpy | DAP | Attach | Launch）

なぜPythonのブレークポイントは動くのか？VS CodeとPythonをつなぐdebugpyとDAPの仕組みを解説し、AttachとLaunchの違いまで構造的に理解する。

【Python×VSCode】debugpyデバッグの全体像｜4軸モデルで整理

VS CodeとdebugpyでPythonデバッグを整理。4軸（実行場所・操作位置・方式・起動形態）で構成を体系的に解説。

当記事ではこの構成パターンのうちの

• Pythonをローカルでデバッグするパターン = ローカルデバッグ

について実装サンプルを使って解説する

ローカルデバッグとは何か？

ローカルデバッグとは

• CodeとPythonが同一環境で動作するデバッグ

のこと。

逆にPythonの実行環境がコンテナの場合はコンテナデバッグと呼ぶこともある

ローカルデバッグの特徴

ローカルデバッグは

• VS CodeとPythonが同じマシン上
• ネットワークを介さない
• 最もシンプルな構成

といった特徴がある。

ローカルデバッグの使いどころ

ローカルにPythonがインストール済みである場合や
簡単なスクリプトを動かす場合に使うことが多い。

逆に実際の開発では、Pythonはローカルではなく
コンテナ上で実行することが主流となってきてるため
実際の開発では使うことは少ない。

デバッグ構成の全体像

ローカル環境では以下の3パターンが存在する

• ローカル × launch
• ローカル × attach × 埋め込み
• ローカル × attach × 外部起動

それぞれのパターン別の実装して動作を確認する

launchデバッグ

launchはVSCodeがPythonプロセスを起動してデバッグする方式。
debugpyはVScodeで使う。

仕組み

仕組みは

Copy
VS Code
  ↓（起動）
Python（debugpy付きで実行）
  ↓
デバッグ開始

のようになるイメージ
VScodeがPythonをdebugpy付きで実行させることでデバッグを開始する。

launchデバッグ実装例

実際にPythonスクリプトをlaunchデバッグしてみる
作成するファイルは

• launch.json
• main.py

で構成は

Copy
|-- .vscode
|   `-- launch.json
`-- main.py

になる。

また「debugpy」をインストールしておく必要もある
下記でインストールできる

Copy
pip install debugpy

.vscode/launch.json

VScodeの実行とデバッグから作成できる

Copy
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python デバッガー: 現在のファイル",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal"
        }
    ]
}

• type: "python" でも動作するが、内部では debugpy が利用されている
• ${file} = 現在VS Codeで開いているファイルのフルパス

main.py

Copy
def main():
    print("hello1")
    print("hello2")
    print("hello3")
    print("hello4")
    print("hello5")

if __name__ == "__main__":
    main()

実行方法

• F5キーで実行
• ブレークポイントが有効
  

attachデバッグ

attachは既に動いているPythonプロセスに後からデバッガを接続する方式。

attachではdebugpyの起動形態が

• 埋め込み
• 外部起動

の2種類あるので、パターン別に実装して動作を確認する

attachデバッグ：debugpy起動形態：埋め込み（import debugpy）

「debugpy起動形態：埋め込み」はdebugpyをPythonプロセスに埋め込む方式。

仕組み

Copy
debugpyを埋め込んだPython（実行中）
  ↓
VS Codeが接続

のようになるイメージ
debugpy埋め込み済みのPythonをで実行し、
VScodeからアタッチしてデバッグを開始する。

attachデバッグ：debugpy起動形態：埋め込み実装例

実際にdebugpy埋め込み済みPythonスクリプトをattachデバッグしてみる
作成するファイルは

• launch.json
• main.py

で構成は

Copy
|-- .vscode
|   `-- launch.json
`-- main.py

になる。

また「debugpy」をインストールしておく必要もある
下記でインストールできる

Copy
pip install debugpy

main.py

Copy
import debugpy

# デバッグクライアント（VS Codeなど）からの接続を受け付けるためのサーバを起動する
debugpy.listen(5678)

# デバッグクライアントが接続されるまで、ここでプログラムの実行を完全に停止する
debugpy.wait_for_client()

def main():
    print("hello1")
    print("hello2")
    print("hello3")
    print("hello4")
    print("hello5")

if __name__ == "__main__":
    main()

• debugpyのコードを埋め込む
• VScodeから接続があるまで待機する

.vscode/launch.json

VScodeの実行とデバッグから作成できる

Copy
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python デバッガー: attach",
            "type": "debugpy",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            }
        }
    ]
}

• connectでdebugpyサーバが待ち受けているアドレス（5678）を指定する

実行方法

まずはpythonスクリプトを実行する

Copy
python main.py

実行後はVScodeからの接続があるまで、プログラムが待っているので動かない

その後にVScodeのattachのデバッガを実行すると

デバッグが開始される

debugpy起動形態：外部起動（python -m debugpy）

「debugpy起動形態：外部起動」はdebugpyを実行時に指定して起動する方式
具体的には起動するコマンドで指定する

仕組み

Copy
python -m debugpy
  ↓
対象スクリプト実行
  ↓
VS Codeが接続

のようになるイメージ
Pythonを実行するコマンドでdebugpyを指定する
その後、VScodeからアタッチしてデバッグを開始する。

attachデバッグ：debugpy起動形態：外部起動実装例

実際にPythonスクリプトをdebugpy付きで外部起動してattachデバッグしてみる
作成するファイルは

• launch.json
• main.py

で構成は

Copy
|-- .vscode
|   `-- launch.json
`-- main.py

になる。

また「debugpy」をインストールしておく必要もある
下記でインストールできる

Copy
pip install debugpy

main.py

Copy
def main():
    print("hello1")
    print("hello2")
    print("hello3")
    print("hello4")
    print("hello5")

if __name__ == "__main__":
    main()

• debugpyはコマンドで外部起動するのでソースには埋め込まない

.vscode/launch.json

VScodeの実行とデバッグから作成できる

Copy
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python デバッガー: attach",
            "type": "debugpy",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            }
        }
    ]
}

• connectでdebugpyサーバが待ち受けているアドレス（5678）を指定する
• VScodeでアタッチする部分は埋め込みと同じ

実行方法

まずはpythonスクリプトをdebugpy付きで実行する

Copy
python -m debugpy --listen 5678 --wait-for-client main.py

• スクリプトの場合はwait-for-clientを指定しないと終了してしまうので指定する
• fastapiなどのREST APIの場合はwait-for-clientを指定しなくても問題ない

その後にVScodeのattachのデバッガを実行すると

デバッグが開始される

launchとattachの本質的な違い

launchとattachの違いは「誰がプロセスを起動するか」にある。

• launch

  • VS CodeがPythonプロセスを起動する

• attach

  • 既に動いているPythonに後から接続する

実務的な使い分け

実際に実務ではどう使い分けるべきかをまとめておく。

launchを使うべきケース

• ローカルでの単体スクリプト開発
• 起動コマンドを自由に変更できる
• とにかく簡単にデバッグしたい

のようにローカルで簡単なpythonツールの動作確認や開発をする場合
に使うことが多い。

attachを使うべきケース

• 既に動いているプロセスをデバッグしたい
• コンテナ・サーバ・バッチなど
• 起動フローを変更できない
• 長時間動くプロセス（APIサーバなど）

のように実際のシステム開発ではAPIサーバーを起動して
VScodeでアタッチしてデバッグする場合に使うことが多い。

attachの中での使い分け

attachはさらに2パターンに分かれる

• debugpy埋め込み
• debugpy外部起動

埋め込みが向いているケース

• 起動方法を変更できない
• 特定の位置で確実に止めたい

外部起動が向いているケース

• コードを汚したくない
• 起動コマンドを制御できる

実務判断まとめ

• ローカル開発

  • launch

• コンテナ・本番に近い環境

  • attach

• attach内の選択

  • 起動制御できる → 外部起動
  • できない → 埋め込み

まとめると

• launchは「IDE主導でプロセスを起動するデバッグ」
• attachは「外部で起動されたプロセスに接続するデバッグ」

という違いになる。

実務では

• ローカル単体開発 → launch
• コンテナ・サーバ・バッチ → attach

となることが多く、特にコンテナ環境ではattachが前提となるため
attachの理解が重要になる。

attachは「起動とデバッグを分離できる」ことが本質であり、
複雑な実行環境ではこの分離が必須になる。