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

Pythonのデバッグについては「debugpy」を
使うことが多いが

• Pythonの実行場所
• デバッグ操作位置
• デバッグ方式
• debugpyの起動形態

の組み合わせによって様々なデバッグ方法がある。
本記事では、デバッグ構成を4つの軸で分解し、すべてのパターンを整理する。
※IDEはVScodeを使用する

debugpyを使ったデバッグ方法の仕組みについては下記記事で解説している
当記事の前に読んでおくと便利

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

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

##　デバッグ構成（4軸）
デバッグ構成は次の4軸で表せる。

Copy
1. Pythonの実行場所
   - ローカルで実行
   - コンテナ上で実行

2. デバッグ操作位置※どこでデバッグを起動するか
   - 内側（同一環境）
   - 外側（リモート）

3. debugpy起動形態
   - 埋め込み（import debugpy）
   - 外部起動（python -m debugpy）

4. デバッグ方式
   - launch
   - attach

Pythonの実行場所

Pythonプログラムをどこで実行しているか？
実行場所としては

• ローカルで実行:ローカルにPythonをインストールして実行
• コンテナで実行:コンテナ上にPythonをインストールして実行

の2種類がある。

デバッグ操作位置

デバッグをどこで起動するのか？
今回の場合であれば、IDEとしてはVScodeを使用するので

• 内側（同一環境）:Pythonが動いている環境と同じ環境でデバッグする

  • Pythonが起動しているコンテナにVSCodeでアタッチでデバッグ

• 外側（リモート）:Pythonが動いている環境と別の環境でデバッグする

  • ローカルのVSCodeからリモートのPythonプロセスにアタッチしてデバッグする

の2種類がある。

debugpyの起動形態

debugpyをどのような形態で起動するのか？
今回の場合であれば、debugpyを

• 埋め込み（import debugpy）
  • プログラム内にデバッグ用のコードを埋め込む形態
• 外部起動（python -m debugpy）
  • コマンドラインでdebugpyを起動する形態

の2種類がある

デバッグ方式

デバッグをどのような方法で行うのか？
今回の場合であれば、debugpyを使ってデバッグするので

• launch:VScodeでPythonプログラムを起動してデバッグを開始
• attach:起動済みのPythonプログラムをVScodeでアタッチしてデバッグを開始

の2種類がある。

デバッグ構成

この4軸の組み合わせが

• デバッグ構成 = 実行場所 × 操作位置 × 方式 × debugpy起動形態

デバッグ構成となる

組み合わせパターン

ただ組み合わせ的にあり得ないものもあるので

• 実行場所はローカルorコンテナ
• launchは同一環境でのみ成立する
• debugpy起動形態は attach のときだけ意識すればよい

の3つを前提とする

実行場所はローカルorコンテナ

今回の整理では、実行場所を

• ローカル
• コンテナ

の2つに限定している。

このときローカル実行とは

• VS Code も Python も同じローカルマシン上にある状態

を指す。
したがってローカル実行に対しては、

• 同じマシンの中からデバッグする

以外の整理をわざわざ独立パターンとして持つ必要がない。

つまり

Copy
1. ローカルに別環境は置かない
   → ローカル × 別環境 を削除

launchは同一環境でのみ成立する

launch は、VS Code が対象の Python プロセスを起動して、そのままデバッグを始める方式である。

つまり launch が成立するには
VS Code がその実行環境に対して直接プロセス起動できること が必要になる。

ローカル実行なら、ローカルの VS Code がローカルの Python を起動できる。
コンテナ内に入ってデバッグしているなら、コンテナ内環境に接続した VS Code がコンテナ内の Python を起動できる。

一方で、コンテナを外から見る構成では、

• Python はコンテナ内で動く
• VS Code はホスト側にいる

ので、VS Code はすでに存在しているコンテナ内プロセスに接続する形になる。
この場合は launch ではなく attach になる。

したがって、

Copy
コンテナ × 別環境
  └ attach のみ

となる。

debugpy起動形態は attach のときだけ意識すればよい

attach は、先にデバッグ対象側で debugpy を待ち受けさせておき、あとから VS Code が接続する方式である。
そのため attach では、debugpy をどう起動するかを自分で決める必要がある。

その起動方法が

• 埋め込み（import debugpy）
• 外部起動（python -m debugpy）

の2種類である。

一方 launch では、VS Code が起動処理の中でデバッグ開始まで面倒を見る。
したがって利用者が「debugpy を埋め込むか、外部起動するか」を分岐として持つ必要がない。

だから debugpy起動形態 は、attach の枝の下にだけ現れる。

デバッグ構成パターン

前提を元にして実用的なデバッグ構成パターンを洗い出すと下記になる

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

このパターン整理は、全組み合わせを列挙したものではない。
「成立しない組み合わせ」を除外した結果、実務上意味のある構成だけを残したものである。

これをデバッグ構成パターンとして列挙すると

• 実行場所:ローカル / 操作位置:同一環境 / 方式:launch / debugpy:―
• 実行場所:ローカル / 操作位置:同一環境 / 方式:attach / debugpy:埋め込み
• 実行場所:ローカル / 操作位置:同一環境 / 方式:attach / debugpy:外部起動
• 実行場所:コンテナ / 操作位置:同一環境 / 方式:launch / debugpy:―
• 実行場所:コンテナ / 操作位置:同一環境 / 方式:attach / debugpy:埋め込み
• 実行場所:コンテナ / 操作位置:同一環境 / 方式:attach / debugpy:外部起動
• 実行場所:コンテナ / 操作位置:別環境 / 方式:attach / debugpy:埋め込み
• 実行場所:コンテナ / 操作位置:別環境 / 方式:attach / debugpy:外部起動

となる。

まとめ

Pythonのデバッグは複雑に見えるが、実際には以下の4軸で整理できる

• 実行場所（ローカル / コンテナ）
• 操作位置（同一環境 / 別環境）
• デバッグ方式（launch / attach）
• debugpy起動形態（埋め込み / 外部起動）

この4軸で分解することで、すべてのデバッグ構成を体系的に理解できる
デバッグは「やり方」を覚えるものではなく

• 構造で理解するもの

である

本記事では、debugpyを用いたデバッグ構成を4軸で整理した

実際の開発では、以下の3パターンを使い分けることが多い

• コンテナにリモートattachする（最も重要）
• コンテナ内でデバッグする
• ローカルでデバッグする

それぞれの具体的な設定方法は、以下の記事で解説する

ローカル × 同一環境 × launch / attach）

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

VS CodeとdebugpyでPythonをローカルデバッグする方法を解説。launchとattachの違いや埋め込み・外部起動の使い分けを実例付きで説明。

※以下は現在執筆中

• 【VS Code】Dockerコンテナにリモートattachする方法
  （コンテナ × 別環境 × attach × 埋め込み / 外部起動）

• 【VS Code】Dockerコンテナ内でPythonをデバッグする方法
  （コンテナ × 同一環境 × launch / attach）