VS Codeで開発コンテナを作る（Create Dev Container）｜devcontainer.jsonの書き方・root実行・複数コンテナ

VS Codeの開発コンテナ（Dev Container）は、プロジェクトに置いた.devcontainer/devcontainer.jsonをもとにDockerコンテナを立て、その中でターミナル・デバッガ・拡張機能を動かす仕組みです。この記事では、開発コンテナを実際に作る手順に絞り、devcontainer.jsonの書き方、rootで動かす設定、ライフサイクルコマンドが走る順番と回数、Docker Composeでの複数コンテナ、VS Codeを使わずに作るDev Container CLIまでを扱います。

挙動の説明は、2026年10月18日時点の拡張機能Dev Containers 0.469.0の公式ドキュメントと、Dev Container CLI 0.89.0をColima上のDocker 29.5.2で実行した結果にもとづきます。開発コンテナの仕組みやDockerとの違い、導入メリットはDev Container（devcontainer）のメリットとは｜Dockerで開発環境を統一する仕組みと設定【2026年版】で解説しています。

まとめ：Create Dev Containerの要点

• 作り方の基本は、フォルダを開いてコマンドパレット（F1）で「Dev Containers: Add Dev Container Configuration Files…」を実行し、テンプレートを選んで「Dev Containers: Reopen in Container」で入る流れです。
• devcontainer.jsonの最小構成はimageの1行です。ツールの追加はfeatures、ビルドキャッシュを効かせたいならDockerfile、DBなど複数サービスはDocker Composeを使います。
• rootで作業したいだけなら"remoteUser": "root"で足ります。コンテナ全体の実行ユーザーまで変えるのはcontainerUserです。
• postCreateCommandは作成時に1回だけ、postStartCommandは起動のたび、postAttachCommandは接続のたびに走ります。依存の導入はpostCreateCommand、起動ごとの初期化はpostStartCommandに置き、サーバーの常駐プロセスはターミナルやタスクから起動します。
• VS Codeを閉じるとコンテナは停止し、削除はされません。設定を変えたら「Rebuild Container」で作り直します。
• Featuresの:1のようなメジャー指定は、そのメジャー内の最新に止まります。node featureは:1だと1.7.1で、最新の2.1.1は入りません。

開発コンテナを作る前提：Docker・拡張機能・対応環境

必要なのは、Dockerが動く環境とVS Codeの拡張機能「Dev Containers」（ID：ms-vscode-remote.remote-containers）の2つです。拡張機能は2026年10月18日時点の安定版が0.469.0（2026年9月8日公開）で、VS Code 1.101以上を要求します（Visual Studio Marketplace）。

公式ドキュメントのシステム要件は、WindowsとmacOSではDocker Desktop 2.0以上、LinuxではDocker CE/EE 18.06以上とDocker Compose 1.21以上を挙げ、Ubuntuのsnap版Dockerは非対応としています。Windowsコンテナイメージも対象外です。Windows 10 HomeはDocker Desktop 2.3以上とWSL 2バックエンドが要ります。WSL上のフォルダを開く手順はWSLで開発環境を構築する手順｜.wslconfig調整とDocker連携・肥大化の対処にまとめています。

Docker Desktop以外の選択肢について、公式ドキュメントの代替手段のページは、macOSのColima（0.2.2以上を推奨）やRancher Desktopで拡張機能を使えると説明しつつ、Docker互換のCLI全般は公式サポートの対象外と書いています。拡張機能の設定dev.containers.dockerPath（既定はdocker）は説明に「Docker (or Podman or WSLc)」とあり、PodmanなどのCLIへ差し替えられます。この記事の検証はDocker Desktopを入れずに、ColimaのDockerソケットへDOCKER_HOSTを向けて行いました。Colimaの導入はColimaとは？MacでDocker Desktopを外す導入手順と設定の落とし穴【0.10系】、Apple製の軽量ランタイムはApple container（apple/container）とは？1.5系の使い方とDockerとの違い・compose代替とGUIの現状を参照してください。Apple containerについては、0.469.0に「Attach to Running Apple Container…」が入っていますが、設定dev.containers.experimentalAppleContainerSupport（既定はfalse）を有効にして使う実験的な機能で、できるのは起動済みコンテナへの接続です。devcontainer.jsonからApple containerでコンテナを作る機能ではありません。

開発コンテナを作る手順：コマンドパレットの3つの入口

VS Codeから開発コンテナを作る入口は、手元のフォルダから作るか、リポジトリから直接作るかで分かれます。失敗したときの逃げ道も用意されています。

既存フォルダから作る：Add Dev Container Configuration Files

1. プロジェクトのフォルダをVS Codeで開きます。
2. コマンドパレット（F1）で「Dev Containers: Add Dev Container Configuration Files…」を実行し、言語やツールのテンプレートを選びます。続いてFeatures（追加ツール）の一覧が出るので、必要なものにチェックを入れます。
3. 生成された.devcontainer/devcontainer.jsonを確認し、「Dev Containers: Reopen in Container」を実行します。初回はイメージの取得とビルドが走ります。

設定を編集してから入る場合はこの順番、すぐ入りたい場合は「Dev Containers: Open Folder in Container…」でフォルダを選ぶと、テンプレート選択からコンテナ起動まで一度に進みます。ローカルの表示に戻すときは「Dev Containers: Reopen Folder Locally」です。0.469.0には「Add Dev Container Configuration Files using GitHub Copilot…」というコマンドもあり、テンプレート一覧から選ぶ代わりにGitHub Copilotに設定ファイルを作らせる入口になっています。

リポジトリから直接作る：Clone Repository in Container Volume

「Dev Containers: Clone Repository in Container Volume…」は、リポジトリをホストのフォルダではなくDockerボリュームへクローンし、そのまま開発コンテナで開きます。リポジトリにdevcontainer.jsonが無ければテンプレートの選択に進みます。macOSやWindowsではバインドマウントよりファイルアクセスが速いことが公式ドキュメントに書かれている一方、ソースがホストのフォルダに無いので、ホスト側のエディタやGUIツールから直接は開けません。

ビルドに失敗したとき：Reopen in Recovery Container

Dockerfileのビルドエラーなどでコンテナが立ち上がらないと、ダイアログに「Reopen in Recovery Container」が出ます。これを選ぶと、Dockerfileなどを編集するための復旧用コンテナに入れます。直したら「Rebuild Container」で作り直します。

devcontainer.jsonの書き方：image・Dockerfile・features

最小構成はimageの1行

devcontainer.jsonは.devcontainer/devcontainer.jsonか、プロジェクト直下の.devcontainer.jsonに置きます。最小構成はimageだけです。以下はポート転送と依存導入も加えた例で、プロジェクト直下にrequirements.txtがあることを前提とします。ファイルがない場合はpostCreateCommandの行を削除してください。

{
  "name": "my-project",
  "image": "mcr.microsoft.com/devcontainers/python:3.14-trixie",
  "forwardPorts": [8000],
  "postCreateCommand": "pip install --user -r requirements.txt"
}

forwardPortsはコンテナ内のポートをホストのlocalhostへ通す設定、postCreateCommandはコンテナ作成後に1回だけ走るコマンドです。VS Code向けの拡張機能や設定はcustomizations.vscode.extensionsとcustomizations.vscode.settingsに書きます。

Dockerfileに切り替える条件

公式ドキュメントは、postCreateCommandよりDockerfileのほうがDockerのビルドキャッシュが効いて再ビルドが速いと説明しています。ただしDockerfileはワークスペースをマウントする前に実行されるので、ソースツリー内のファイル（requirements.txtやpackage.json）はマウント経由では読めず、使うにはビルドコンテキストに含めてCOPYで取り込む必要があります。OSパッケージや言語ランタイムはDockerfile、ソースを書き換えるたびに入れ直すnpm installなどはpostCreateCommand、と分けるのが基準です。

{
  "name": "custom-build",
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  }
}

Dockerfileそのものの書き方はDockerfileとは｜書き方・主要命令・ベストプラクティスを解説【2026年版】で扱っています。

Featuresでツールを足す：メジャー版の固定に注意

Featuresは、Node.jsやGitHub CLI、Docker CLIなどを宣言だけでコンテナに入れる仕組みです。公式のFeaturesはGitHubのdevcontainers/featuresにあり、2026年10月18日時点でnode・python・docker-in-docker・copilot-cliなど28種類です。

{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/node:2": { "version": "lts" }
  }
}

見落としやすいのが末尾の:1や:2です。これはFeature自体のメジャー版の指定で、そのメジャー内の最新に解決されます。node:1で作ったコンテナに対してdevcontainer outdatedを実行すると、次のように出ました。

Feature                              Current  Wanted  Latest
ghcr.io/devcontainers/features/node  1.7.1    1.7.1   2.1.1

node:1のままでは、2.0.0（2026年4月28日）で入ったnpmVersionオプションなど2系の変更は入りません。入るNode.js本体はversionオプションで決まり、"lts"指定で24.22.0でした。Featureを足したビルドには、この環境で約2分かかりました。

Dev Container CLI 0.89.0でコンテナを作ると、.devcontainer/devcontainer-lock.jsonが自動で生成され、Featureの版とダイジェストが記録されました。VS Code側でロックファイルが既定で作られるようになった経緯はVS Code 1.118の新機能｜codebase semantic index・devcontainer-lock.json・Copilot設定の変更点で扱っています。チームで同じ版を使うなら、ロックファイルもリポジトリにコミットします。

remoteUserとcontainerUserの違い：rootで動かす設定

公式イメージの多くは、vscodeという非rootユーザー（UID 1000）で作業する設定になっています。主要イメージのうちjavascript-nodeとtypescript-nodeはnodeユーザーです。パッケージを入れるだけなら、公式イメージにはsudoが設定済みなので、ユーザーを変えずにsudo apt-get installで済みます。それでもrootで作業したい場合の設定は2つあり、効く範囲が違います。

devcontainer.jsonリファレンスの定義では、remoteUserはVS Codeなどのツールと、そこから起動するターミナル・タスク・デバッグの実行ユーザーで、コンテナ全体の実行ユーザーは変えません。containerUserはコンテナ内のすべての処理の実行ユーザーを上書きします。mcr.microsoft.com/devcontainers/base:ubuntuで3通りを作り、devcontainer execで確かめた結果が次の表です。

作業をrootで行いたいだけならremoteUserで足ります。containerUserは、イメージのUSERがrootで、起動するプロセスまで非rootにしたいときに使います。

{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "remoteUser": "root"
}

注意点はLinuxホストでのファイル所有者です。リファレンスによると、LinuxではupdateRemoteUserUID（既定はtrue）がコンテナ内ユーザーのUID/GIDをホストのユーザーに合わせ、バインドマウントの権限問題を防ぎます。CLIのソースを読むと、この処理は対象ユーザーがrootか数値UIDのときは飛ばされます。rootで作ったファイルはUID 0のままなので、Linuxホストではroot所有のファイルがワークスペースに残ります。macOSのColima（virtiofs）では、どの設定で作ったファイルもホスト側では自分のUID（501）に見えました。

ライフサイクルコマンドの実行順と回数：初回・再接続・再作成

devcontainer.jsonには、コンテナの作成や起動のタイミングで走るコマンドが6つあります。リファレンスの説明だけでは「いつ・何回」走るかがつかみにくいので、6つすべてにユーザー名をログへ書き出すコマンドを入れ、Dev Container CLIで操作を変えて記録しました。表の「起動中に再接続」は起動中のコンテナに対するdevcontainer upの再実行、「停止後に再起動」はdocker stop後のdevcontainer upです。

「作り直し」はdevcontainer up --remove-existing-containerで、既存コンテナを消して作り直す操作です。所要時間は、イメージ取得を含む初回が56秒、再接続と停止後の再起動がそれぞれ4秒、作り直しが6秒でした（Intel MacのColima上）。initializeCommandだけがホストのユーザーで動き、残り5つはコンテナ内のvscodeユーザーで、作業ディレクトリは/workspaces/<フォルダ名>でした。

この表から、置き場所の判断は次のようになります。

• 依存パッケージの導入（npm install、pip install）はpostCreateCommand。作り直しのたびに入り直し、再起動では走りません。
• DBマイグレーションやファイアウォール設定のように、コンテナ起動のたびに必要な初期化はpostStartCommand。
• ホスト側で事前に作っておくファイル（.envの雛形など）はinitializeCommand。再接続でも毎回走るので、何度実行しても結果が変わらない書き方にします。

公式ドキュメントは、postCreateCommandは終了するコマンドでなければならず、アプリの起動を入れるとコンテナが立ち上がらないと注意しています。サーバーを常駐させたい場合はここに書かず、ターミナルやタスクから起動します。VS Codeが接続を待つのは、リファレンス上のwaitForの既定であるupdateContentCommandまでで、postCreateCommandは接続後に裏で走ります。

複数コンテナの作り方：Docker Composeでアプリとデータベースを組む

アプリとデータベースのように複数のサービスが要る場合は、dockerComposeFileでComposeファイルを渡し、VS Codeが入るサービスをserviceで指定します。imageやbuildとの併用はできません。

// .devcontainer/devcontainer.json
{
  "name": "app-and-db",
  "dockerComposeFile": "compose.yaml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "shutdownAction": "stopCompose"
}

# .devcontainer/compose.yaml
services:
  app:
    image: mcr.microsoft.com/devcontainers/base:ubuntu
    volumes:
      - ..:/workspace:cached
    command: sleep infinity
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: postgres

command: sleep infinityは、アプリ側のコンテナが即座に終了しないようにするための指定です。..:/workspaceは.devcontainerの1つ上、つまりプロジェクトのフォルダだけを共有します。公式テンプレート（javascript-node-postgresなど）のComposeファイルにある../..:/workspacesは親フォルダごとマウントするため、隣の別プロジェクトまでコンテナから見えます。

この構成をdevcontainer upで立ち上げると、初回は32秒、コンテナを作り直した2回目は6秒で2つのコンテナが起動しました。appからdbというサービス名で名前解決でき、5432番ポートにも接続できましたが、起動直後の1回目は接続を拒否され、その後の再試行で通りました。postCreateCommandでマイグレーションを流すなら、Compose側にhealthcheckを書いてdepends_onのcondition: service_healthyで待たせるか、コマンド内で接続を再試行させます。データベースのクライアントはlocalhostではなくdbをホスト名にします。

公式ドキュメントは、DBをlocalhostで扱いたい場合の手として、appにnetwork_mode: service:dbを付けてDBと同じネットワークに乗せる方法を示しています。Compose自体の書き方はdocker-composeとは？複数コンテナをymlで定義し一括管理する仕組みを解説で解説しています。

言語別テンプレートと公式イメージのタグ

土台イメージは、mcr.microsoft.com/devcontainers/配下の公式イメージを使うのが手早い方法です。2026年10月18日にレジストリのタグ一覧から確認した主な指定は次のとおりです。

base:ubuntuのような版を書かないタグは、時期によって中身が変わります。2026年10月に取得したbase:ubuntuはUbuntu 26.04.1 LTS（イメージのリリースv0.4.35、2026年10月9日）でした。24.04を前提にしたスクリプトがあるなら、ubuntu24.04のように版を書いて固定します。

Pythonのテンプレートを適用すると、既定の選択肢は3.14-trixieで、生成されるimageはpython:3-3.14-trixieのように先頭にイメージ自体のメジャー版が付きます。テンプレートの説明には、ローカルのApple Silicon（arm64）では-trixieか-bookworm付きを選ぶよう書かれています。FlutterやGodotのように公式イメージが無い環境は、base:ubuntuにDockerfileでSDKを入れて作ります。

コンテナの終了・再ビルド・削除

VS Codeのウィンドウを閉じたときの動きはshutdownActionで決まります。既定は、imageやDockerfileの構成ならstopContainer、Docker ComposeならstopComposeで、どちらもコンテナを停止するだけで削除しません。次に「Reopen in Container」を実行すると同じコンテナが再起動するので、postCreateCommandは走り直しません。閉じても動かし続けたい場合は"shutdownAction": "none"にします。

VS Codeはdevcontainer.jsonやDockerfileを編集しても自動では再ビルドしません。変更を反映するのは次のコマンドです。

• 「Dev Containers: Rebuild Container」：コンテナを作り直します。手で入れたソフトウェアは消えるので、残したいものはDockerfileかpostCreateCommandに書きます。
• 「Dev Containers: Rebuild Container Without Cache」：Dockerのビルドキャッシュを使わずに作り直します。ローカルで開いている状態からは「Rebuild Without Cache and Reopen in Container」です。

使い終わった開発コンテナは、コマンドパレットの「Dev Containers: Clean Up Dev Containers…」で選んで消せます。Docker側で消す場合は、docker ps -aで確認してdocker rm・docker rmiを使います。Dev Containersが作ったコンテナにはdevcontainer.local_folderというラベルが付き、元のフォルダのパスが入っているので、docker ps -a --filter label=devcontainer.local_folderで絞り込めます。コンテナの起動・停止コマンドの使い分けはDockerコンテナ起動コマンドの使い分け｜run・start・execと起動しない時の対処にまとめています。

VS Codeなしで作る：Dev Container CLIの使い方

同じdevcontainer.jsonは、npmパッケージ@devcontainers/cliのコマンドdevcontainerでも扱えます。CIで開発環境と同じコンテナを使いたいときや、VS Code以外のエディタを使う人がいるチームで役立ちます。2026年10月18日時点の最新は0.89.0（2026年8月31日公開）で、Node.js 20以上が必要です。

npm install -g @devcontainers/cli

# テンプレートからdevcontainer.jsonを作る（Add Dev Container Configuration Filesに相当）
devcontainer templates apply --workspace-folder . \
  --template-id ghcr.io/devcontainers/templates/python \
  --template-args '{"imageVariant":"3.14-trixie"}'

# コンテナを作って起動する（Reopen in Containerに相当）
devcontainer up --workspace-folder .

# コンテナ内でコマンドを実行する
devcontainer exec --workspace-folder . python --version

# Featureの更新状況を確認する
devcontainer outdated --workspace-folder .

templates applyはPythonテンプレートの場合、.devcontainer/devcontainer.jsonに加えて.github/dependabot.ymlも生成しました。イメージだけを作るdevcontainer buildもあります。CIでビルドしたイメージをレジストリへ公開し、各メンバーのdevcontainer.jsonでそのイメージを参照すれば、手元で必要なビルド処理を減らせます。

AIエージェントを開発コンテナで動かす：Claude Code・Copilot CLI・Codex

AIコーディングエージェントを開発コンテナに入れると、エージェントが実行するコマンドはホストではなくコンテナの中で動きます。ただし、マウントしたホスト側のファイルには書き込めますし、Dockerの通常のネットワークでは外部へも通信できます。触れるファイルはマウントの範囲で、通信先はファイアウォールなどで別に絞ります。

Claude Codeは、公式ドキュメントDevelopment containersが導入方法を示しています。既存のdevcontainer.jsonに"ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}をFeatureとして足すだけで入り、末尾の:1.0はインストールスクリプトの版で、Claude Code本体は最新版が入って自動更新されます。同じページは、確認なしで実行する--dangerously-skip-permissionsをCLIがroot起動では拒否すると書いており、remoteUserを非rootにしておくよう求めています。前の章でrootにしたコンテナでは、この使い方ができません。

より固めた例として、公式リポジトリの.devcontainerに参照実装があります。Dockerfile・devcontainer.json・init-firewall.shの3ファイルで、runArgsに--cap-add=NET_ADMINと--cap-add=NET_RAWを付け、postStartCommandでファイアウォールのスクリプトを実行し、waitForをpostStartCommandにしています。スクリプトは外向き通信を既定で拒否し、GitHubのIP範囲、registry.npmjs.org、api.anthropic.com、VS Codeのマーケットプレイスなど列挙した宛先だけを許可します。実行順の表のとおりpostStartCommandは起動のたびに走るので、停止後に再起動してもファイアウォールが張り直されます。公式ドキュメントは、このスクリプトと2つの権限はClaude Code自体には不要で、ネットワーク制限を別の方法で行うならなくてよいとしています。Claude Code側の権限設定はClaude Codeのパーミッションモードの違いと設定方法｜auto・acceptEdits・bypassPermissionsの使い分けで扱っています。

GitHub Copilot CLIは、公式Featureのghcr.io/devcontainers/features/copilot-cli:1（2026年10月時点で1.1.3）で入れられます。Copilot CLIの動作モードとインストールはGitHub Copilot CLIのAutopilotとは｜使い方・止まる条件・料金と導入手順【2026年9月】を参照してください。

OpenAIのCodexは、公式ドキュメントAgent approvals & securityに「Run Codex in Dev Containers」という節があります。ホストでLinuxのサンドボックスが動かない場合や、組織がコンテナでの開発に統一している場合に、Dev Containersを外側の隔離境界にする使い方です。コンテナ内では、Dev Containerの構成がbwrapに必要な権限を与えていればCodex自身のサンドボックスを有効のまま使い、コンテナを隔離境界とみなすなら--sandbox danger-full-accessで二重のサンドボックスを作らない、の2択が示されています。後者について同じ節は、悪意のあるプロジェクトがコンテナ内のCodexの認証情報まで持ち出せると警告し、信頼できるリポジトリに限るよう求めています。

どの方法でも、バインドマウントしたワークスペースはエージェントが書き換えられます。未コミットの変更を消されないよう、作業前にコミットしておく運用は変わりません。チームで開発コンテナとCIの環境をそろえる体制づくりは、DevOps・CI/CD導入支援でもご相談いただけます。

開発コンテナを避けたほうがよい場面

• iOSやmacOSのアプリをXcodeでビルドする開発：Dev ContainersのコンテナはLinuxで、公式の対応表もLinuxコンテナのみです。
• Windowsコンテナが前提の.NET Framework開発：公式ドキュメントがWindowsコンテナイメージを非対応と明記しています。
• Linuxホストで、ワークスペースのファイルをホスト側の別ツールからも触る運用で、rootで作業したい場合：前述のとおりUIDの合わせ込みが効かず、root所有のファイルが残ります。remoteUserは非rootのままsudoを使うほうが安全です。

よくある質問

Create Dev Containerはどこから実行しますか？

VS Codeでフォルダを開き、コマンドパレット（F1）から「Dev Containers: Add Dev Container Configuration Files…」を実行してテンプレートを選び、「Dev Containers: Reopen in Container」でコンテナに入ります。拡張機能「Dev Containers」とDockerが必要です。

開発コンテナをrootで動かすには？

devcontainer.jsonに"remoteUser": "root"を書き、「Rebuild Container」を実行します。ターミナルやデバッガがrootで動きます。コンテナ全体の実行ユーザーを変えるのはcontainerUserです。Linuxホストではrootで作ったファイルがホスト側でもroot所有になります。

VS Codeを閉じるとコンテナは消えますか？

消えません。既定のshutdownActionはコンテナの停止で、次に「Reopen in Container」を実行すると同じコンテナが再起動します。作り直すのは「Rebuild Container」を実行したときです。

devcontainer.jsonを変えたのに反映されないのはなぜですか？

VS Codeは設定ファイルの変更で自動的に再ビルドしないためです。「Dev Containers: Rebuild Container」を実行します。postCreateCommandは作成時にしか走らないので、再起動だけでは追加したコマンドが実行されません。

Docker Desktopが無くても開発コンテナは作れますか？

Docker互換の環境があれば動く場合がありますが、公式サポートの対象はDocker Desktop（Windows・macOS）とDocker CE/EE（Linux）です。この記事の検証では、ColimaのソケットをDOCKER_HOSTに指定したDev Container CLI 0.89.0でコンテナの作成・接続・Compose構成まで動きました。

関連記事

• Dev Container（devcontainer）のメリットとは｜Dockerで開発環境を統一する仕組みと設定【2026年版】
• VS Code 1.118の新機能｜codebase semantic index・devcontainer-lock.json・Copilot設定の変更点
• docker-composeとは？複数コンテナをymlで定義し一括管理する仕組みを解説
• Colimaとは？MacでDocker Desktopを外す導入手順と設定の落とし穴【0.10系】
• GitHub Copilot CLIのAutopilotとは｜使い方・止まる条件・料金と導入手順【2026年9月】