Contents
Docker デバッグ機能の概要とインストール手順
Docker が公式に提供している デバッグ支援ツール は、主に以下 3 種類です。
- docker debug（実験的）コマンド – コンテナ起動時にデバッガ用のオプションを自動付与します。
- Docker Desktop の Debug モード – Daemon の詳細ログ取得と設定変更が可能です。
- 公式ドキュメントで紹介されている補助スクリプト（例:
docker‑debug.sh） – GitHub の docker/cli リポジトリにサンプルが掲載されています。
本記事では、2026 年 4 月時点の公式情報 (Docker Docs – Debugging containers) を元に、実際に利用できる手順と注意点を解説します。
ポイント
Docker が提供するデバッグ機能は「ツールボックス」形式の単体配布ではなく、CLI と Desktop の設定を組み合わせて使用します。そのためインストールは不要ですが、実験的コマンドやサンプルスクリプトを取得したい場合は公式リポジトリからダウンロードしてください。
実験的 docker debug コマンドの有効化（Linux/macOS）
|
1 2 3 4 5 6 7 8 9 |
# Docker CLI のバージョンが 24.0 以上であることを確認 docker version | grep "Version:" # → 24.x 系 # experimental 機能を有効にするため、~/.docker/config.json に設定を追加 jq '. + {"experimental": "enabled"}' ~/.docker/config.json > tmp && mv tmp ~/.docker/config.json # Docker デーモンの再起動（Linux の場合） sudo systemctl restart docker |
根拠：
docker debugは Docker CLI 24.0‑beta 以降で実験的に提供されている機能です (Docker Docs, 2026‑04)。
この状態で docker debug run を使用すると、デバッグ用のシェルが自動で注入されたコンテナが起動します。
|
1 2 |
docker debug run -it --name myapp_debug myimage bash |
コンテナの標準出力・エラー取得とシェルでの手動調査
コンテナ内部の挙動を把握する第一歩は、ログ取得 と インタラクティブシェル の併用です。以下では安全に実行できるベストプラクティスを紹介します。
docker logs と docker attach の使い分け
docker logs -f --tail N <container>は過去 N 行だけ表示しつつ、リアルタイムで追記を取得できます。docker attach --sig-proxy=falseはコンテナの TTY に直接接続しますが、Ctrl‑C がコンテナ停止につながるリスクがあるため、シグナルプロキシ無効化 を必ず付与してください。
|
1 2 3 4 5 6 |
# 直近 30 行を追跡 docker logs -f --tail 30 my_container # シグナルをプロキシしないで接続（デタッチは Ctrl‑P + Ctrl‑Q） docker attach --sig-proxy=false my_container |
参考：Docker Docs の
logsとattach解説ページ (2026‑03) を参照。
docker exec -it で安全にシェルを起動する方法
| シナリオ | 推奨コマンド例 |
|---|---|
| デフォルトの root シェル（bash が利用可能） | docker exec -it my_container /bin/bash |
非 root ユーザーで限定的に操作したい場合 (例: vscode) |
docker exec -u vscode -it my_container /bin/sh |
| デバッグツールだけを一時的に注入する場合 | docker exec -it --privileged my_container /usr/bin/strace -p 1 |
注意：
--privilegedは最小限の範囲で使用し、作業後はコンテナを再生成してください。
言語別バッファリング回避設定
| 言語 | バッファ無効化手段（Dockerfile 例） |
|---|---|
| Python | ENV PYTHONUNBUFFERED=1 |
| Node.js | ENV NODE_OPTIONS="--inspect --no-warnings" |
| Go | CMD ["dlv", "exec", "/app/main"] （Delve デバッガ利用） |
Dockerfile に上記環境変数を追加するだけで、docker logs への出力遅延が大幅に減少します。
まとめ
ログ取得は docker logs・docker attach を使い分け、シェル操作は最小権限の docker exec -it が安全です。言語固有のバッファ設定を併用すれば、リアルタイムに状態を把握できます。
Docker Desktop の Debug モード活用法
Docker Desktop では Debug モード をオンにすると、Daemon が詳細なトレース情報を出力します。これはコンテナ起動失敗やネットワーク障害の根本原因解析に有効です。
設定手順（GUI）
- Docker Desktop の Settings → Docker Engine を開く
- JSON エディタで
"debug": trueを追加し、Apply & Restart をクリック
|
1 2 3 4 5 |
{ "experimental": false, "debug": true } |
設定手順（CLI・Linux）
Docker Desktop が利用できない環境（例: Linux のみ）は ~/.docker/daemon.json に同様の記述を行い、デーモンを再起動します。
|
1 2 3 4 |
sudo mkdir -p /etc/docker echo '{"debug":true}' | sudo tee /etc/docker/daemon.json sudo systemctl restart docker |
出典：Docker Desktop 公式ガイド (2026‑02)
デバッグログの保存場所と閲覧例
| OS | ログパス |
|---|---|
| macOS | ~/Library/Containers/com.docker.docker/Data/log/vm/docker.log |
| Windows | %APPDATA%\Docker\docker.log |
| Linux | /var/lib/docker/daemon.log |
|
1 2 3 |
# 例: macOS で最近のエラーメッセージだけ抽出 grep -i "error" ~/Library/Containers/com.docker.docker/Data/log/vm/docker.log | tail -n 20 |
ポイント
- ログは JSON 形式ではなくプレーンテキストなので、jq より grep・awk が便利です。
- Debug モードは大量の情報を出力するため、必要な箇所だけフィルタリングして確認しましょう。
VS Code Remote - Containers で構築する統一デバッグ環境
VS Code の Remote – Containers 拡張機能は、開発・デバッグ用コンテナをワンステップで立ち上げられるため、ローカルと同様の体験が可能です。以下では、2026 年版 VS Code (1.88 系) と Docker Desktop 2026‑04 の組み合わせで実装できる devcontainer.json の例を示します。
基本構成（devcontainer.json）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
{ "name": "Superhero Debug Environment", "dockerFile": "Dockerfile", "context": "..", "runArgs": [ "--cap-add=SYS_PTRACE", // デバッガが必要とする権限 "-e", "PYTHONUNBUFFERED=1", // Python の出力をリアルタイム化 "-e", "NODE_OPTIONS=--inspect" ], "remoteUser": "vscode", "features": { "ghcr.io/devcontainers/features/python:1": { "version": "3.12" }, "ghcr.io/devcontainers/features/node:2": { "nodeVersion": "20" } }, "postCreateCommand": "pip install -r requirements.txt && npm ci" } |
dockerFile：同ディレクトリに置くDockerfile（後述）を参照します。runArgsの--cap-add=SYS_PTRACEは GDB/Delve などのネイティブデバッガが必要とする権限です。remoteUserを非 root に設定し、セキュリティを向上させています。
デバッグ構成例（Python）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
{ "version": "0.2.0", "configurations": [ { "name": "Python: Remote Attach", "type": "python", "request": "attach", "connect": { "host": "localhost", "port": 5678 }, "pathMappings": [ { "localRoot": "${workspaceFolder}", "remoteRoot": "/workspaces/${containerWorkspaceFolder}" } ] } ] } |
Node.js の場合は "type": "node" に変更し、runArgs に -p 9229:9229 を追加すれば同様にリモートアタッチできます。
Dockerfile のサンプル
|
1 2 3 4 5 6 7 8 9 |
FROM python:3.12-slim # デバッグツールをインストール（例: debugpy, ptvsd） RUN pip install --no-cache-dir debugpy && \ apt-get update && apt-get install -y strace WORKDIR /workspaces/project COPY . . |
まとめ
VS Code の Remote‑Containers と devcontainer.json を活用すれば、言語別バッファ設定やデバッグ権限を自動化した環境が数クリックで構築できます。
コンテナ起動失敗時のトラブルシューティングフローとリモートデバッグ実装例
コンテナが期待通りに起動しないケースは多岐にわたります。以下では、体系的なチェックリスト と VS Code からのリモートアタッチ手順 を組み合わせたフローを示します。
1️⃣ ビルドエラーの確認
|
1 2 |
docker build -t myapp . | tee build.log |
build.logにエラーメッセージが出力されたら、まずは Dockerfile の構文とキャッシュクリア (--no-cache) を検証します。- ビルド成功後は
docker image inspect myappでメタデータを確認し、EntrypointとCmdが期待通りか確かめます。
2️⃣ ENTRYPOINT / CMD の書式ミス例
| 正しい記述 | 誤った記述 |
|---|---|
ENTRYPOINT ["python", "app.py"] |
ENTRYPOINT python app.py |
CMD ["--port","8080"] |
CMD --port 8080 |
シェル形式は環境変数展開が期待通りに動かないことがあるため、exec 形式（配列） を基本としてください。
3️⃣ ポート競合の検出
|
1 2 |
docker ps -a --filter "publish=8080" |
同一ホストポートを使用しているコンテナが存在すれば、-p 0.0.0.0:0:8080 と書いて Docker に自動割当させ、docker port <id> で取得した実際のポートに VS Code から接続します。
4️⃣ リモートデバッグ用コンテナ起動例
|
1 2 3 4 5 6 |
docker run -d \ -p 127.0.0.1:5678:5678 \ # ローカル限定で公開 --name debug_app \ --cap-add=SYS_PTRACE \ myapp |
VS Code のコマンドパレットから 「Remote‑Containers: Attach to Running Container」 を選び、debug_app に接続します。launch.json の port と remoteRoot が一致すれば、ブレークポイントが有効になります。
5️⃣ セキュリティ上の留意点
| 項目 | 推奨設定 |
|---|---|
| ポート公開 | 127.0.0.1 バインドでローカル限定にする |
| 権限付与 | --cap-add=SYS_PTRACE はデバッグ時のみ使用し、作業後はイメージを再ビルド |
| ベースイメージ | 公式の python, node, alpine 系統を選択し、サードパーティ製イメージはハッシュで検証 |
6️⃣ 環境更新手順（Docker Desktop & VS Code）
- Docker Desktop：Settings → General → Check for updates。2026‑04 のリリースノートに VS Code 1.88 系との互換性が明記されています。
- VS Code：拡張機能パネルで「Remote – Containers」の Update ボタンを押すか、Marketplace のバージョン情報 (2026‑04) を確認してください。
公式情報は常に Docker Docs（Debugging containers）と VS Code Release Notes を参照するのが最も確実です。
フローチャートまとめ
1. ビルドログ → 2. docker inspect で Entrypoint 確認 → 3. ポート競合チェック → 4. デバッグモード／リモートアタッチ → 5. 必要なら docker debug run または docker exec -it でシェル操作。
記事の要点（まとめ）
- Docker が提供するデバッグ機能は 実験的 CLI (
docker debug)、Docker Desktop の Debug モード、そして 公式サンプルスクリプト の３本柱です。 docker logsとdocker attachは取得目的で使い分け、docker exec -itでは最小権限を意識してシェルに入ります。言語別バッファ無効化設定を Dockerfile に組み込むとリアルタイム性が向上します。- Docker Desktop の Debug モードは Daemon の詳細ログ取得に必須で、
debug: true設定後は OS 毎のログパスから検索できます。 - VS Code Remote – Containers と
devcontainer.jsonによる環境構築は、デバッグ権限や環境変数をコード化できるため、チーム全体で同一設定を共有可能です。 - 起動失敗時は ビルドログ → イメージ検査 → ポート競合 → リモートアタッチ の順に切り分け、セキュリティはローカルバインドと最小権限で確保します。
これらの手順を体系的に実践すれば、Docker コンテナのデバッグが「Superhero」級のスピードと安定性で行えるようになります。