devcontainer.json properties

devcontainer.json は接続先コンテナの設定を記載します。

Property Type 説明
Dockerfile or image
image string Required イメージ使用時。 作成コンテナのレジストリ内イメージ名 (DockerHub, Github Container Registry, Azure Container Registry)
build.dockerfile / dockerFile string Required when Dockerfile使用時. Dockerfile の場所。 devcontainer.json からの相対パス。vscode-dev-containers repository に多数のサンプルあり。
build.context / context string Dockerビルドする場所を、 devcontainer.json からの相対パスで指定。 省略時は ".".
build.args Object Docker image build arguments Dockerビルド時の引数をname-valueペアで指定。環境変数や pre-defined variables が使用できます. 省略時は設定されません。 例: "build": { "args": { "MYARG": "MYVALUE", "MYARGFROMENVVAR": "${localEnv:VARIABLE_NAME}" } }
build.target string Docker image build target Dockerビルド時のターゲットを指定。省略時は設定されません。例: "build": { "target": "development" }
appPort integer,string,array 新しい forwardPorts property の使用を推奨。コンテナからローカルに 公開 するポートを指定。forwardPorts と違い、localhost だけでなく全てのインターフェイス (0.0.0.0) をリッスンする必要があります。省略時は []
containerEnv object コンテナで上書きする環境変数をname-valueペアで指定。環境変数や pre-defined variables が使用できます。例: "containerEnv": { "MY_VARIABLE": "${localEnv:MY_VARIABLE}" } 適用するにはコンテナの再構築が必要。
remoteEnv object コンテナ全体は変えずに、VSCode(またはターミナルなどのサブプロセス)だけで上書きする環境変数をname-valueペアで指定。環境変数や pre-defined variables が使用できます。ターミナルで有効にならない時は Terminal > Integrated: Inherit Env の設定を確認してください。例:"remoteEnv": { "PATH": "${containerEnv:PATH}:/some/other/path", "MY_VARIABLE": "${localEnv:MY_VARIABLE}" }適用するにはVSCode ウィンドウのリロードが必要。
containerUser string コンテナ内のユーザーを指定。省略時は root かイメージ作成時に使用されたDockerfileの最後の USERです。Linuxでは、指定されたユーザーの UID/GID がローカルユーザーの UID/GID と同じに更新され、ボリュームバインド時のパーミッション問題を回避します。 (updateRemoteUserUID で無効にした場合を除く。)適用するにはコンテナの再構築が必要。
remoteUser string VSCodeがコンテナ内で実行するユーザーを指定。(ターミナル、タスク、デバッグなどのサブプロセス)。省略時は containerUserと同じ。Linuxじは, containerUser と同様にUID/GIDを制御します。適用するにはVSCodeウィンドウのリロードが必要。ただしUID/GIDの更新はコンテナの再構築が必要。
updateRemoteUserUID boolean trueならLinuxでは, containerUserremoteUser が指定されると、ユーザーの UID/GID がローカルユーザーの UID/GID と同じに更新され、ボリュームバインド時のパーミッション問題を回避します。falseにするとこの動作を行いません。 省略時は true。適用するにはコンテナの再構築が必要。
mounts array コンテナの作成時に追加するマウントポイントの配列です。各値は、 Docker CLI --mount flagと同じ値を受け入れる文字列です。環境変数やpre-defined variables が使用できます。 例: "mounts": ["source=${localWorkspaceFolder}/app-scripts,target=/usr/local/share/app-scripts,type=bind,consistency=cached"] ⚠️ Codespacesは、Dockerソケットを除いて「bind」マウントを無視します。
workspaceMount string コンテナの作成時にワークスペースのデフォルトのローカルマウントポイントをオーバーライドします。Docker CLI --mount flagと同じ値をサポートします。主に リモートコンテナの設定ディスクパフォーマンスの向上に役立ちます。環境変数やpre-defined variables が使用できます。 例: "workspaceMount": "source=${localWorkspaceFolder}/sub-folder,target=/workspace,type=bind,consistency=cached"⚠️ コードスペースではまだサポートされていません。また、コンテナボリュームでクローンリポジトリを使用する場合もサポートされていません。
workspaceFolder string VS Code がコンテナに接続するときに開くデフォルトのパスを設定します。通常、workspaceMountと組み合わせて使用します。省略時はソースコードの自動マウント場所。⚠️ CodespacesでDocker Composeを使用する場合と、Container VolumeでClone Repositoryを使用する場合のみサポートされます。
runArgs array コンテナ実行時のDocker CLI arguments を指定。省略時は[]。例えば, C++などのptraceベースのデバッガがコンテナ内で動作させるには: "runArgs": [ "--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined" ]
overrideCommand boolean コンテナの起動時に、コンテナのデフォルトコマンドの代わりに、/bin/sh -c "while sleep 1000; do :; done" を実行するかどうかを指示します。省略時は true。 これはデフォルトのコマンドが終了するとコンテナがシャットダウンしてしまうのを防ぐためです。
shutdownAction enum ウィンドウが閉じられたとき、またはシャットダウンされたときに、VS Code がコンテナを停止するかどうかを示します。値は nonestopContainer (default). ⚠️ Codespaces には適用されません。
Docker Compose
dockerComposeFile string,array Required. Docker Compose使用時。 devcontainer.json からの相対パスを指定。arrayを使用するとDocker Compose 設定を拡張する 際に便利です。その場合順序は大事です。.env ファイルは通常プロジェクトルートのが使われますが、env_file を利用すると別の場所を指定できます。
service string Required. VSCodeが接続するDocker Composeファイル内のサービス名を指定。
runServices array VSCodeが起動すべきDocker Composeファイル内のサービスリストを指定。通常これらは切断時にシャットダウンされますが、"shutdownAction""none" にすると起動したままになります。省略時は全サービスです。
workspaceFolder string コンテナ接続時に最初に開く場所を指定。 (多くの場合コンテナ内でソースコードがあるボリュームマウントへのパストなるでしょう。)省略時は "/"
remoteEnv object Dockerfile or imageの場合と同じ。
remoteUser string Dockerfile or imageの場合と同じ。
shutdownAction enum ウィンドウが閉じられたとき、またはシャットダウンされたときに、VS Code がコンテナを停止するかどうかを示します。値は nonestopCompose (default). ⚠️ DCodespacesでは適用されません。
General
name string コンテナの表示名を指定。
extensions array コンテナ作成時にインストールするVSCode拡張機能を指定。省略時は []
settings object デフォルトの settings.json に追加する値を指定。
forwardPorts array コンテナからローカルに転送するポートを指定。
portsAttributes object 転送する特定ポートのプロパティを指定。ポート番号、範囲、正規表現が使用できる。
otherPortsAttributes object portsAttributes で指定されていないポートのプロパティを指定。
postCreateCommand string,array コンテナ作成後にコンテナ内で実行されるコマンドを指定。コマンドは workspaceFolder で実行されます。文字列に&&を使うと複数コマンドを実行できます。例: "yarn install""apt-get update && apt-get install -y curl"。 配列版だと ["yarn", "install"] となりこちらはシェルを経由せずに直接実行されます。ソースコードがマウントされた後に起動するので、ソースツリーのシェルスクリプトを実行することもできます。例: bash scripts/install-dev-tools.sh。省略時は何もしない。
postStartCommand string,array コンテナ起動時にコンテナ内で実行されるコマンドを指定。postCreateCommand と同様ですが、作成時ではなく起動時に毎回実行されます。省略時は何もしない。
postAttachCommand string,array postCreateCommandpostStartCommand と同様で、アタッチ時にコンテナ内で実行されるコマンドを指定。省略時は何もしません。
initializeCommand string,array コンテナ作成前に ローカルで実行されるコマンドを指定。ローカルの workspaceFolder で実行されます。Windows/macOS/Linux のパス変換に対応しています。 ⚠️ コマンドはソースコードがどこにあっても実行されます。Codespacesではローカルではなくクラウド上で実行されます。
userEnvProbe enum デバッグ中やタスク実行中にデフォルトで使用するユーザー環境変数の「プローブ」にVS Codeが使用するシェルの種類を示します: none (default), interactiveShell, loginShell, or loginInteractiveShellが指定できます。 Interactive shells には通常 /etc/bash.bashrc.bashrc に設定された変数が含まれ、login shells には通常これらの “rc” ファイルと /etc/profile.profile に設定された変数が含まれます。省略時は none。none以外だと起動が遅くなる可能性があります。
devPort integer S Code Serverがコンテナ内で使用する特定のポートを強制的に指定することができます。省略時はランダムな利用可能なポートが設定されています。

Formatting string vs. array properties

postCreateCommand, postStartCommand, postAttachCommand, and initializeCommand は配列指定と文字列指定ができます。runArgs は配列指定飲みできます。 配列指定はシェルを使わずに直接OSにコマンドを流します。文字列指定はシェル経由です。

runArgs はコマンドラインで使うときはスペースを含む引数はシングルクォートで囲みますが、アプリケーションにはシングルクォートが除去されたものが渡されます。 そのため、 devcontainer.json の記載はシングルクォートはない状態で指定します。

Variables in devcontainer.json

devcontainer.json 内では ${variableName} の形でいくつか変数が参照できます。

Variable Properties 説明
${localEnv:VARIABLE_NAME} Any ローカル の環境変数 (VARIABLE_NAMEの部分)。未設定の環境変数は空白になります。例えばLinux / macOSではローカルのホームディレクトリ、Windowsではユーザーフォルダに変数を設定するには: "remoteEnv": { "LOCAL_USER_PATH": "${localEnv:HOME}${localEnv:USERPROFILE}" } (未指定は空白になるルールを使用) ⚠️ Codespacesではホストはクラウドになります。
${containerEnv:VARIABLE_NAME} remoteEnv コンテナ の環境変数(VARIABLE_NAMEの部分)。例: "remoteEnv": { "PATH": "${containerEnv:PATH}:/some/other/path" }
${localWorkspaceFolder} Any VS Codeで開いたローカルディレクトリ(.devcontainer/devcontainer.json を含む)のパス。コンテナボリュームでClone Repositoryを使用する場合は未対応です。
${containerWorkspaceFolder} Any コンテナのワークスペースファイルがあるディレクトリ
${localWorkspaceFolderBasename} Any ${localWorkspaceFolder}パスのディレクトリ名。コンテナボリュームでClone Repositoryを使用する場合は未対応です。
${containerWorkspaceFolderBasename} Any ${containerWorkspaceFolder}パスのディレクトリ名。

Attached container configuration reference

Attached container configuration filesdevcontainer.json に似ていて、その一部をサポートしています。

Property Type 説明
workspaceFolder string VS Code がコンテナに接続する際に開くべきデフォルトのパスを設定します(これは多くの場合、コンテナ内でソースコードを見つけることができるボリュームマウントへのパスです)。デフォルトでは設定されていません(空のウィンドウが開かれます)。
extensions array コンテナの作成時に、コンテナ内にインストールされるべきエクステンションを指定するエクステンションIDの配列です。デフォルトでは[]が設定されます。
settings object デフォルトの settings.json の値を、コンテナ/マシン固有の設定ファイルに追加します。
forwardPorts array コンテナ内からローカルマシンにフォワードされるべきポートのリストです。
remoteEnv object コンテナ全体ではなく、VS Code(またはターミナルなどのサブプロセス)の環境変数を設定または上書きする名前と値のペアのセット。環境変数やpre-defined variables が使用できます。例: "remoteEnv": { "PATH": "${containerEnv:PATH}:/some/other/path" }
remoteUser string S Code がコンテナ内で(ターミナル、タスク、デバッギングなどのサブプロセスと一緒に)実行されるユーザをオーバーライドする。デフォルトでは、コンテナ全体が実行されているユーザー(多くの場合、root)になります。
postAttachCommand string,array VS Code がコンテナにアタッチされた後に実行されるコマンド文字列またはコマンド引数のリストです。複数のコマンドを実行するには、文字列の中で && を使用します。例えば、"yarn install""apt-get update && apt-get install -y curl" などです。配列構文 ["yarn", "install"] を使用すると、シェルを使用せずにコマンド(ここでは yarn )を直接起動します。デフォルトでは設定されていません。

Variables in attached container configuration files

attached container configuration files内で ${variableName} の形で変数が使用できます。

Variable Properties Description
${containerEnv:VAR_NAME} remoteEnv コンテナ内の環境変数 (この場合, VAR_NAME) を参照。例: "remoteEnv": { "PATH": "${containerEnv:PATH}:/some/other/path" }