VS Code Dev Containersで作るPython開発環境（Docker入門）

Pythonで開発を進めていると、「プロジェクトごとにライブラリのバージョンが異なる」「他の人の環境では動かない」といった問題に直面することがあります。本記事では、VS Code Dev Containersを用いたDockerコンテナによるPython開発環境の構築手順を解説します。

前提条件： 本記事は、Docker入門シリーズの内容（コンテナの基本操作、Dockerfile、ボリューム・ネットワーク、Docker Compose）を理解していることを前提としています。

一つ前の記事はこちらです。Docker Composeによる複数コンテナの構成管理と起動の自動化について解説しています。

目次

• なぜDockerでPython開発環境を作るのか
• 事前準備
• プロジェクトの構成
  • プロジェクトフォルダの作成
  • ファイルの準備
• devcontainer.json の作成と解説
• Dev Containerを起動して開発する
• ファイル編集の即時反映について
• まとめ
• 関連記事

なぜDockerでPython開発環境を作るのか

Pythonの環境構築には、大きく分けて3つの方法があります。ローカルに直接インストールする方法、仮想環境を使う方法、そしてDockerコンテナを使う方法です。それぞれの特徴を整理すると、以下のようになります。

Dockerコンテナを使う最大の利点は環境の再現性です。Dockerfileとrequirements.txtさえ共有すれば、チームの誰が・どのOSで構築しても、同一の環境が手に入ります。ただし、そのままでは、コンテナの中でコードを編集するには、ターミナルからvimなどのエディタを使うか、ホスト側で編集してコンテナにコピーする必要があります。

この不便さを解消するのが、VS Codeの拡張機能「Dev Containers」です。Dev Containersを使うと、VS Codeがコンテナの中に接続し、あたかもローカルで開発しているかのような操作感で、コンテナ内のファイルを直接編集できます。拡張機能（Pylanceなどの補完ツール）もコンテナ内にインストールできるため、ローカル開発と変わらない環境をコンテナ上で実現します。

事前準備

本記事の手順を進めるにあたり、以下の3つを準備します。

Docker Desktop：
Docker Desktopのインストール方法はこちら。インストール済みであればそのまま使用できます。Docker Desktopが起動していることを確認してください。

Visual Studio Code：
公式サイトからダウンロードしてインストールします。インストール済みの場合は最新版へのアップデートを推奨します。Dev Containers拡張機能は比較的新しいVS Codeのバージョンを前提としているため、古いバージョンでは正常に動作しない場合があります。

Dev Containers 拡張機能：
VS Codeを開き、左側の拡張機能アイコン（四角が4つ並んだマーク）をクリックして、検索欄に「Dev Containers」と入力します。Microsoft公式の「Dev Containers」拡張機能が表示されるので、「インストール」をクリックします。

プロジェクトの構成

プロジェクトフォルダの作成

Dev Containerで開発するためのプロジェクトフォルダを作成します。

Dev Containers拡張機能が認識するのは、プロジェクトフォルダの中にある.devcontainer フォルダとその中の devcontainer.json です。プロジェクトフォルダ自体の名前は何でも構いません。ここではmy-projectという名前のフォルダにし、以下の構成でファイルを用意します。

my-project/
├── .devcontainer/
│   ├── devcontainer.json
│   └── Dockerfile
├── requirements.txt
└── main.py

.devcontainer フォルダは、Dev Containers拡張機能が認識する特別なフォルダです。VS Codeがプロジェクトを開いた際、このフォルダ内の devcontainer.json を読み取り、どのようなコンテナを構築するかを判断します。.devcontainer というフォルダ名と devcontainer.json というファイル名はいずれもDev Containersの仕様で決められた固定名です。これらの名前を変更すると拡張機能に認識されないため、そのまま使用してください。

各ファイルの役割は以下の通りです。

後述するdevcontainer.json の build.dockerfile で指定するパスを変えれば、別の名前のファイルを使うこともできます。ただし、Dockerfile という名前がDockerの慣例として広く使われているため、特別な理由がなければそのまま Dockerfile としておくのが無難です。複数のDockerfileを使い分ける場合（開発用と本番用など）に、名前を変えるケースがあります。

ファイルの準備

Dockerfile：
Python開発用のイメージを定義します。

FROM python:3.13-slim

WORKDIR /workspace

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

python:3.13-slim は、Python公式が提供する軽量イメージで、DockerHubで公開されています。フルイメージと比較してサイズが小さく、開発用途には十分な機能を備えています。WORKDIR /workspace で作業ディレクトリを /workspace に設定し、requirements.txt に記載されたライブラリをインストールしています。

requirements.txt：
動作確認用として、まずは1つだけライブラリを記載しておきます。

requests==2.32.3

実際のプロジェクトでは、使用するライブラリを必要に応じて追加します。

main.py：
環境が正しく構築されたことを確認するための簡単なスクリプトです。

import sys
import requests

print(f"Python version: {sys.version}")
print(f"Requests version: {requests.__version__}")
print("Dev Container is working!")

このスクリプトは、Pythonのバージョンとrequestsライブラリのバージョンを表示します。Dev Container起動後にこのファイルを実行し、コンテナ内の環境が期待通りであることを確認します。

devcontainer.json の作成と解説

devcontainer.json は、Dev Containersの中心となる設定ファイルです。「どのようなコンテナを作るか」「VS Codeにどの拡張機能を入れるか」「どのような設定を適用するか」をこのファイル1つで管理します。

.devcontainer/devcontainer.json に以下の内容を記述します。

{
    "name": "Python Development",
    "build": {
        "dockerfile": "Dockerfile",
        "context": ".."
    },
    "customizations": {
        "vscode": {
            "extensions": [
                "ms-python.python",
                "ms-python.vscode-pylance"
            ],
            "settings": {
                "python.defaultInterpreterPath": "/usr/local/bin/python"
            }
        }
    },
    "postCreateCommand": "pip install --no-cache-dir -r requirements.txt",
    "remoteUser": "root"
}

各設定項目の意味は以下の通りです。

拡張機能IDの調べ方：

extensions に記述するIDは、VS Codeの拡張機能画面から確認できます。左側の拡張機能アイコンから対象の拡張機能を検索し、クリックして詳細画面を開きます。「Identifier」の欄に表示されている文字列が、devcontainer.json に記述するIDです。

補足：postCreateCommand と Dockerfile の RUN の違い：

requirements.txt のインストールが、Dockerfileの RUN 命令と postCreateCommand の両方に記述されていますが、これらの役割は異なります。

Dockerfileの RUN は、イメージのビルド時に実行されます。ビルドされたイメージにはインストール済みのライブラリが含まれるため、コンテナの起動が速くなります。一方、postCreateCommand は、コンテナが作成された後に毎回実行されます。requirements.txt を更新した際、イメージを再ビルドしなくても、コンテナを作り直すだけで最新のライブラリが反映されるという利便性があります。

開発中に頻繁にライブラリを追加・変更する段階では postCreateCommand が便利ですが、環境が安定したらDockerfileの RUN だけに集約し、postCreateCommand を削除しても構いません。

Dev Containerを起動して開発する

ここまでで作成したファイルを使って、実際にDev Containerを起動し、コンテナ内でPythonスクリプトを実行するまでの流れを確認します。

手順1：プロジェクトフォルダをVS Codeで開く
VS Codeを起動し、メニューの「ファイル」→「フォルダーを開く」から、先ほど作成したプロジェクトフォルダを開きます。

手順2：Dev Containerで開き直す
VS Codeの左下にある緑色（または青色）の「><」アイコンをクリックし、表示されるメニューから「コンテナーで再度開く（Reopen in Container）」を選択します。

あるいは、Ctrl + Shift + P（macOSでは Cmd + Shift + P）でコマンドパレットを開き、「Dev Containers: Reopen in Container」と入力して実行しても同じ操作ができます。

手順3：コンテナのビルドを待つ
初回は、Dockerイメージのビルドとコンテナの作成が行われるため、数分程度かかります。VS Codeの右下に表示される「Starting Dev Container...」の通知をクリックすると、ビルドログを確認できます。

ビルドが完了すると、VS Codeが自動的にコンテナ内に接続された状態で再表示されます。左下の「><」アイコンの表示が「Dev Container: Python Development」のように変わっていれば、コンテナへの接続は成功です。

手順4：Pythonスクリプトを実行する
VS Code内のターミナル（Ctrl + @ で開く）で、以下のコマンドを実行します。

python main.py

次のように表示されれば、コンテナ内のPython環境が正しく構築されています。

root@d54c7eaf8c9a:/workspaces/my-project# python main.py
Python version: 3.13.13 (main, May  8 2026, 20:06:31) [GCC 14.2.0]
Requests version: 2.32.3
Dev Container is working!

手順5：コード補完の動作を確認する
環境が正しく動作していることを確認したら、コード補完も試してみましょう。main.py を開き、requests. と入力してみてください。Pylanceによる補完候補が表示されれば、拡張機能もコンテナ内で正常に動作しています。

ファイル編集の即時反映について

Dev Containersでは、ホスト側のプロジェクトフォルダがコンテナ内の /workspace にマウントされています。そのため、VS Code上でファイルを編集・保存すると、その変更はコンテナ内にも即座に反映されます。逆に、コンテナ内のターミナルからファイルを作成した場合も、ホスト側のフォルダに反映されます。これは、バインドマウントと同じ仕組みです（バインドマウントについてはこちらの記事で解説しています）。以下のように、一行追加して保存します。

import sys
import requests

print(f"Python version: {sys.version}")
print(f"Requests version: {requests.__version__}")
print("Dev Container is working!")
print("Code Change!") # 追加

再度ターミナルから実行すると、以下のように結果が追加されていることを確認できます。

Python version: 3.13.13 (main, May  8 2026, 20:06:31) [GCC 14.2.0]
Requests version: 2.32.3
Dev Container is working!
Code Change!

まとめ

本記事では、VS CodeのDev Containers拡張機能を使い、Dockerコンテナ上にPython開発環境を構築する手順を解説しました。

Dev Containersを使うことで、Dockerコンテナの「環境の再現性」と「使い捨てできる気軽さ」を活かしながら、VS Codeによるコード補完やデバッグといった快適な開発体験を両立できます。一度 .devcontainer フォルダを用意してしまえば、チームメンバーは「Reopen in Container」を実行するだけで、全員が同じ環境で開発を始められます。

今回作成した設定は最小構成のため、実際のプロジェクトでは必要に応じてカスタマイズしてみてください。例えば、devcontainer.json の extensions にフォーマッタ（Black）やリンター（Ruff）を追加したり、Docker Composeと組み合わせてデータベースを含む環境を構築したりすることも可能です。

関連記事