【Python×VSCode】Dockerコンテナ内Pythonをリモートデバッグする方法

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

Copy
ホストOS
└─ VS Code

Dockerコンテナ
├─ Python
└─ debugpy

Copy
docker compose up

Copy
コンテナ上でPython起動
↓
debugpy待受
↓
ローカルからVS Codeがattach
↓
デバッグ開始

Copy
|-- .vscode
|   `-- launch.json
|-- Dockerfile
|-- docker-compose.yml
|-- main.py
`-- requirements.txt

Copy
debugpy

Copy
# 軽量＆最新系に更新（2026時点で安定して使いやすい）
FROM python:3.12-slim

# pipを最新化 + キャッシュ削減
RUN python -m pip install --upgrade pip && \
    pip install --no-cache-dir --upgrade setuptools wheel

# 作業ディレクトリ
WORKDIR /app

# 依存関係を先にコピー（レイヤーキャッシュ最適化）
COPY requirements.txt .

# パッケージインストール（キャッシュ無効）
RUN pip install --no-cache-dir -r requirements.txt

Copy
version: "3"
services:
  container_python_remote_debug:
    container_name: "container_python_remote_debug"

    # Dockerfileをビルド
    build:
      context: .
      dockerfile: Dockerfile
    tty: true

    # プロジェクトをバインドマウント
    volumes:
      - .:/app
    ports:
      - "5678:5678"

Copy
ports:
  - "5678:5678"

Copy
ホストのVS Code
  ↓ localhost:5678
Docker Port Mapping
  ↓
debugpy

Copy
VS Code（ホストOS）
        ↓
localhost:5678
        ↓
Docker Port Mapping
        ↓
debugpy埋め込み済みPython
        ↓
デバッグ開始

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

Copy
import debugpy

# コンテナ外から接続できるようにする
debugpy.listen(("0.0.0.0", 5678))

# VS Codeから接続されるまで待機
debugpy.wait_for_client()

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

if __name__ == "__main__":
    main()

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

Copy
debugpy.listen(5678)

Copy
0.0.0.0

Copy
debugpy.wait_for_client()

Copy
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python デバッガー: コンテナ attach",
      "type": "debugpy",
      "request": "attach",
      "justMyCode": false,
      "connect": {
        "host": "localhost",
        "port": 5678
      },
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}",
          "remoteRoot": "/app"
        }
      ]
    }
  ]
}

Copy
$ docker exec -it container_python_remote_debug bash
root@cc7fb729bb77:/app# python main.py
0.00s - Debugger warning: It seems that frozen modules are being used, which may
0.00s - make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
0.00s - to python to disable frozen modules.
0.00s - Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.

Copy
debugpy.wait_for_client()

Copy
VS Code（ホストOS）
        ↓
localhost:5678
        ↓
Docker Port Mapping
        ↓
python -m debugpy
        ↓
main.py

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

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

if __name__ == "__main__":
    main()

Copy
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python デバッガー: コンテナ attach",
      "type": "debugpy",
      "request": "attach",
      "justMyCode": false,
      "connect": {
        "host": "localhost",
        "port": 5678
      },
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}",
          "remoteRoot": "/app"
        }
      ]
    }
  ]
}

Copy
$ docker exec -it container_python_remote_debug bash
root@c4a02a6eef54:/app# 
root@c4a02a6eef54:/app# python -m debugpy \
  --listen 0.0.0.0:5678 \
  --wait-for-client \
  main.py
0.01s - Debugger warning: It seems that frozen modules are being used, which may
0.00s - make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
0.00s - to python to disable frozen modules.
0.00s - Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.

Copy
ホスト
└─ project
   └─ main.py

コンテナ
└─ /app
   └─ main.py

Copy
ホストのVS Code側のパス

↓

コンテナのPython側のパス

Copy
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python デバッガー: コンテナ attach",
      "type": "debugpy",
      "request": "attach",
      "connect": {
        "host": "localhost",
        "port": 5678
      },
      "pathMappings": [
        {
          "localRoot": "${workspaceFolder}",
          "remoteRoot": "/app"
        }
      ]
    }
  ]
}

Copy
volumes:
  - .:/app

Copy
ホスト
└─ project
   └─ main.py

コンテナ
└─ /app
   └─ main.py

Copy
RUN pip install fastapi sqlalchemy pydantic

Copy
/usr/local/lib/python3.12/site-packages/

Copy
Dockerコンテナ
├─ /app
│  └─ main.py
│
└─ /usr/local/lib/python3.12/site-packages
   ├─ fastapi
   ├─ sqlalchemy
   └─ pydantic

Copy
/usr/local/lib/python3.12/site-packages/fastapi

Copy
コンテナ側
/usr/local/lib/python3.12/site-packages/fastapi

↓

ホスト側
???

Copy
/app

Copy
{
  "justMyCode": true
}

Copy
python -m venv .venv

pip install -r requirements.txt

Copy
ホスト
└─ .venv

コンテナ
└─ site-packages

Copy
version: "3"
services:
  container_python_remote_debug:
    container_name: "container_python_remote_debug"

    # Dockerfileをビルド
    build:
      context: .
      dockerfile: Dockerfile
    tty: true

    # プロジェクトをバインドマウント
    volumes:
      - .:/app
    ports:
      - "5678:5678"

    command: >
      python -m debugpy
      --listen 0.0.0.0:5678
      --wait-for-client
      main.py

Copy
docker compose up

Copy
Dockerコンテナ
├─ VS Code
├─ Python
└─ debugpy

Copy
ホストOS
└─ VS Code

Dockerコンテナ
├─ Python
└─ debugpy

Copy
VS Code（コンテナ内）
      ↓ localhost
debugpy（コンテナ内）

Copy
VS Code（ホスト）
      ↓ localhost:5678
Docker Port Mapping
      ↓
debugpy（コンテナ内）

Copy
ports:
  - "5678:5678"

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

Copy
python -m debugpy \
  --listen 0.0.0.0:5678

Copy
"pathMappings": [
  {
    "localRoot": "${workspaceFolder}",
    "remoteRoot": "/app"
  }
]

Copy
debugpy.wait_for_client()

Copy
【コンテナ × 別環境 × attach × 外部起動】

┌──────────────────────────────┐
│ ホストPC                     │
│                              │
│  VS Code                     │
│  launch.json                 │
│  request: attach             │
│  connect: localhost:5678     │
└───────────────┬──────────────┘
                │
                │ Docker port forward
                │ localhost:5678 → container:5678
                ▼
┌──────────────────────────────┐
│ Dockerコンテナ                │
│                              │
│  Python / FastAPI / Flask    │
│  Django / バッチ処理          │
│                              │
│  python -m debugpy           │
│    --listen 0.0.0.0:5678     │
│    main.py                   │
└──────────────────────────────┘

Copy
【コンテナ × 別環境 × attach × 外部起動】

┌──────────────────────────────┐
│ ホストPC                     │
│                              │
│  VS Code                     │
│  launch.json                 │
│  request: attach             │
│  connect: localhost:5678     │
└───────────────┬──────────────┘
                │
                │ Docker port forward
                │ localhost:5678 → container:5678
                ▼
┌──────────────────────────────┐
│ Dockerコンテナ                │
│                              │
│  Python / FastAPI / Flask    │
│  Django / バッチ処理          │
│                              │
│  python -m debugpy           │
│    --listen 0.0.0.0:5678     │
│    main.py                   │
└──────────────────────────────┘