こんにちは。テックリードの私だ。
日々のPython開発において、ローカル環境では完璧に動いていたコードが、Dockerコンテナという「ブラックボックス」に入れた瞬間に沈黙する——。この絶望的な瞬間を、君は幾度となく経験してきたはずだ。
「なぜか `KeyError` で落ちるが、原因がログから追えない」
「`docker run` した瞬間にコンテナが即死し、ブレークポイントを仕込む暇すらない」
ネットを検索すれば「`import pdb; pdb.set_trace()` を書け」という初心者向けの記事が山のように出てくる。しかし、コンテナの孤立したプロセス空間、標準入力（STDIN）のルーティング、そしてシグナルの不整合という壁に阻まれたとき、それらの薄い知識は全く役に立たなくなる。
今回は、Docker環境下における `pdb` / `ipdb` の挙動の裏側を完全に解き明かし、開発速度を極限まで引き上げるプロの実践テクニックを伝授しよう。
—
1. なぜDocker環境でのデバッグは泥沼化するのか？
まず、Dockerコンテナ内で `pdb` を使う際に何が起きているのか、そのアーキテクチャを理解する必要がある。
通常、`pdb` は対話型デバッガーであり、標準入力（`stdin`）からのキーボード入力を待機し、標準出力（`stdout`）に実行コンテキストを描画する。しかし、Dockerコンテナはデフォルトで「デーモン的」にバックグラウンド実行されるか、あるいはTDD/CIのパイプラインの一部として非対話型（Non-interactive）で起動する。
ここに `-it`（interactive + tty）オプションの付け忘れや、Docker Composeにおける `stdin_open` / `tty` の欠落が加わると、Pythonプロセスは `stdin` を失い、以下のようなエラーを吐いて即死する。
> `EOFError: EOF when reading a line`
この根本原因を断ち切るための、インフラストラクチャとコード側のベストプラクティスを見ていこう。
—
2. 実践！Docker Compose構成のベストプラクティス
チーム開発において、誰もが同じ環境でシームレスにデバッグを行えるようにするためには、`docker-compose.yml` の設計が命運を分ける。
以下に示すのは、プロセスが途中で落ちてもアタッチでき、かつ対話型デバッグを完全に担保するプロダクション・グレードの構成例だ。
version: ‘3.8’
services:
web:
build: .
# コンテナ内のGunicornやUvicorn、あるいはメインのPythonスクリプトを指定
command: python main.py
volumes:
# ホストのソースコードをリアルタイムでコンテナに同期（変更即反映）
- .:/app
environment:
- PYTHONUNBUFFERED=1 # 標準出力・標準エラーのバッファリングを無効化し、ログを即座に端末へ流す
- PYTHONDONTWRITEBYTECODE=1 # .pycファイルの生成を抑制し、意図しないキャッシュトラブルを防ぐ
# 【最重要】これがないとpdbが標準入力を受け付けずEOFErrorで即死する
stdin_open: true # docker run -i に相当
tty: true # docker run -t に相当
ports:
- “8000:8000”
なぜ `stdin_open: true` と `tty: true` が必要なのか？
Dockerのバックグラウンドプロセスは、デフォルトでは仮想端末（TTY）を持たない。`pdb` は内部で `sys.stdin` を監視しているため、TTYが割り当てられていない空間では入力を受け取ることができない。この2つの設定を有効にすることで、ホストのターミナルとコンテナ内のPythonプロセス間に仮想的なパイプラインが確立されるのだ。
—
3. 圧倒的な視認性を手に入れる：IPython + ipdb の導入
標準の `pdb` は強力だが、シンタックスハイライトがなく、補完機能（Tab補完）も貧弱だ。実務において、デバッグスピードを2倍にするために必ず導入すべき「神パッケージ」がある。
それが `ipdb` だ。
依存関係の定義 (`pyproject.toml` or `requirements.txt`)
プロダクション環境には不要だが、開発環境（Development）には必須のパッケージ群となる。
[tool.poetry.dependencies]
python = “^3.10”
fastapi = “^0.100.0”
[tool.poetry.group.dev.dependencies]
ipython = “^8.14.0” # 高機能対話型シェル
ipdb = “^0.13.13” # ipythonベースのpdbラッパー
開発を加速させる `.pdbrc`（設定ファイルの共有化）
チームメンバー全員のデバッグ体験を統一し、毎回手動で入力する手間を省くために、プロジェクトのルートディレクトリに `.pdbrc` を配置する。これは `pdb` / `ipdb` が起動した瞬間に自動実行される初期化スクリプトだ。
.pdbrc – ipdb起動時の初期化設定
エイリアスの設定により、タイポを防ぎ、キーストロークを最小化する
‘n’ (next) を打つ代わりに ‘nn’ で高速実行
alias n next
‘s’ (step) を ‘ss’ に
alias s step
‘c’ (continue) を ‘cc’ に
alias c continue
現在のスコープの変数をきれいなJSON形式でダンプするカスタムコマンド
alias pjson import json; print(json.dumps(self.curframe.f_locals, default=str, indent=2))
例外発生時に自動的にスタックトレースの変数を表示させる設定（一部バージョン依存）
set log
この `.pdbrc` がリポジトリに含まれているだけで、チーム全体のデバッグ作法が標準化され、コードレビュー時のトラブルシューティング効率が劇的に向上する。
—
4. 現場で使える！アタッチとリモートデバッグの極意
ここからが本番だ。すでに起動しているDockerコンテナ、あるいはデーモンとして動いているWebアプリにどうやって割り込み、ブレークポイントをヒットさせるのか。
シチュエーションに応じた2つのアプローチをマスターしてほしい。
パターンA: `docker attach` による既存プロセスへの介入
もしコンテナがフォアグラウンドで動いており、標準入出力がターミナルに結びついているなら、以下のコマンドで直接コンテナのメインプロセスにアタッチできる。
実行中のコンテナIDまたはサービス名を確認してアタッチ
docker attach
注意: コード内に `breakpoint()`（Python 3.7以降の標準ビルトイン）を仕込んでおき、その行が実行された瞬間に、このアタッチしたターミナル上に `ipdb>` のプロンプトが出現する。
パターンB: 起動中のコンテナへのインタラクティブ・シェル侵入
すでにバックグラウンド（`-d` オプション等）で動いているコンテナに対しては、`docker exec` で新しいTTYプロセスを生成し、そこにアタッチする。
コンテナ内部のbashシェルにインタラクティブに接続
docker exec -it
しかし、これだけでは「すでに動いているPythonプロセス」の内部状態をデバッグすることはできない。動中のプロセスに介入したい場合は、シグナル（SIGUSR1など）をトラップして `pdb` を起動する高度なテクニックが必要になる。だが、もっとスマートな方法がある。それが リモートデバッグ（`debugpy` / `rpdb`） の活用だ。
—
5. 詰まりポイントの完全解決：リモートデバッグのベストプラクティス
Webフレームワーク（FastAPI, Djangoなど）をDocker上で動かしている場合、標準の `pdb` ではマルチスレッドやリロードの挙動に阻まれてうまく停止しないことがある。
ここで、ポートフォワーディングを利用したリモートデバッグの構成を導入する。
1. デバッグ用ポートの解放 (`docker-compose.yml`)
services:
web:
build: .
command: python -m debugpy –listen 0.0.0.0:5678 –wait-for-client main.py
ports:
- “8000:8000”
- “5678:5678” # デバッガー接続用のポートを追加
2. コード側でのブレークポイント設定
Python 3.7以降であれば、ビルトインの `breakpoint()` が使える。内部で環境変数 `PYTHONBREAKPOINT` を見ているため、これを書き換えるだけでデバッガーの種類を切り替えられる。
Dockerfile または docker-compose.yml の環境変数で制御
ENV PYTHONBREAKPOINT=ipdb.set_trace
これにより、コード内の任意の場所で `breakpoint()` と書くだけで、Dockerコンテナのコンソール（あるいはIDEのリモートデバッグセッション）に処理がシームレスに捕捉される。
—
6. プロが実践する隠れたキーボードショートカット＆テクニック
`ipdb` のプロンプトに入った後、マウスを使ってコードを行ったり来たりしているようでは一流とは言えない。以下のショートカットを手に覚え込ませろ。
- `l` (list): 現在実行されている行の周囲のコードを表示する。「今どこにいるんだっけ？」と思った瞬間に打つ癖をつけろ。
- `w` (where): コールスタック全体を表示する。自分がどの関数のどの階層から呼ばれてここにたどり着いたのか、即座に俯瞰できる。
- `u` / `d` (up / down): コールスタックのフレームを上下に移動する。呼び出し元の変数の状態を確認したいときに神のように機能する。
- `!` (exclamation mark): 変数名とpdbのコマンドが衝突したとき（例: `c` という名前の変数を扱いたいとき）、`!c` と打つことでPythonの式として評価させることができる。
- `pp` (pretty print): 複雑な辞書型や巨大なオブジェクト構造を見やすく整形して出力する。
—
最後に：デバッグ能力はインフラ理解の深さに比例する
Docker環境下での `pdb` デバッグがうまくいかない原因の9割は、「コンテナのプロセス空間とI/O（標準入出力）のルーティング」を理解していないことにある。
「なぜ動かないのか」を勘で修正するのではなく、Dockerの仕様とPythonのランタイム挙動をロジカルに結びつけて考えること。それこそが、トラブルシューティングを最短で終わらせ、チーム全体の開発スピードを爆発的に引き上げるテックリードの思考法だ。
今日からあなたのプロジェクトの `docker-compose.yml` と `.pdbrc` を見直し、真のコントロールを手に入れてほしい。