当サイトは、アフィリエイト広告を利用しています

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

作成日：2026月03月28日
更新日：2026年03月28日

PythonのデバッグをVS Codeで行う際

  • なぜブレークポイントが効くのか?
  • どうやってIDEと実行中のPythonが連携しているのか?

が気になったので調べてみた。

本記事では、その中核にある

  • debugpy
  • DAP（Debug Adapter Protocol）

の仕組みを整理し、さらに実務で重要となる

  • Attach / Launch の違い

を解説する。

debugpyとは何か

debugpyとは、

  • Pythonを外部から制御可能にするためのデバッグ接続レイヤ

である。

より本質的には以下の役割を持つ。

  • IDE（VS Codeなど）とPython実行環境の間を仲介する
  • デバッグ操作をPython実行に変換する

通常のPythonは以下のような操作を外部から受け付けない。

  • 実行停止（ブレークポイント）
  • ステップ実行
  • 変数の取得

debugpyはこれらを可能にする「通訳層」として機能する。

DAP（Debug Adapter Protocol）とは？

debugpyを理解するには、DAPの理解が不可欠である。

DAPとは

  • IDEとデバッガ間の通信仕様（共通プロトコル）

である。

なぜ必要か?

もしDAPが存在しない場合、以下の問題が発生する。

  • VS Code × Python → 専用実装
  • VS Code × Java → 別実装
  • IntelliJ × Python → また別実装

つまり、組み合わせごとに実装が爆発する。

これを解決するために

example.text
IDE ←→ DAP ←→ デバッガ

という構造に抽象化されている。

debugpyとの関係

  • debugpyは DAPサーバとして動作
  • VS Codeは DAPクライアント

つまり、

  • VS Codeは「命令を送る側」
  • debugpyは「それをPython操作に変換する側」

である。

このDAPが、実際のデバッグ時にどのように使われるのかを全体構造で見る。

仕組み：全体アーキテクチャ

VS CodeでPythonをdebugpy経由でデバッグする構造は以下の通りである。

example.text
VS Code（DAP Client）
   ↓
DAP通信
   ↓
debugpy（DAP Server + Debugger）
   ↓
Pythonプロセス

各レイヤの責務

IDE（DAP Client）

  • ブレークポイント設定
  • Continue / Step命令
  • 変数取得要求

debugpy

  • DAPメッセージをPython操作に変換
  • Pythonの状態をDAPレスポンスとして返す

Pythonプロセス

  • 実際のユーザーコードが実行される

通信モデル

debugpyは基本的にサーバとして動作する。

example.text
VS Code → debugpy → Python

つまり「IDEが接続する」モデルである。

仕組み：AttachとLaunchの違い

debugpyの利用方法は大きく2つに分かれる。

  • Attach
  • Launch

この違いは「誰がPythonを起動するか」に集約される。

Attach：既存プロセスへの後付けデバッグ

Attachとは、すでに動いているPythonプロセスに後から接続する方式である。

実行フロー

example.text
Python起動
  ↓
debugpyが待機
  ↓
VS Codeが接続

Python側の実装

example.py
import debugpy


debugpy.listen(("0.0.0.0", 5678))
debugpy.wait_for_client()


def main():
    print("hello")


if __name__ == "__main__":
    main()
  • listen()：接続待ち受け
  • wait_for_client()：接続まで停止

特徴

  • プロセス主導：Python側
  • IDEは後から接続
  • 本番環境に近い構成で使いやすい

Launch：IDE主導のデバッグ起動

Launchとは、IDEがdebugpy付きでPythonを起動する方式である。

実行フロー

example.text
VS Codeが実行（F5）
  ↓
debugpy付きでPython起動

Python側の実装

example.py
def main():
    print("hello")


if __name__ == "__main__":
    main()
  • debugpyコードは不要

特徴

  • プロセス主導：IDE
  • セットアップがシンプル
  • 開発用途に最適

実務での判断基準

Attachを選ぶべきケース

  • 既存プロセスをデバッグしたい
  • Docker / Kubernetes環境
  • 本番に近い動作確認

Launchを選ぶべきケース

  • ローカル開発
  • 単体スクリプトの検証
  • セットアップを簡単にしたい

判断の本質

違いは一つに集約できる。

  • Attach = 外部から侵入するデバッグ
  • Launch = 最初からデバッグ込みで起動

まとめ

debugpyは単なるツールではなく、「デバッグを外部化するためのアーキテクチャ」である。
この視点を持つことで、環境に依存しないデバッグ設計が可能になる。

関連記事

新着記事

タグ一覧
top