Docker Composeのenv_file、environment、.envの違い

Docker Compose env_fileガイド

Docker Composeのenv_file、environment、.envの違いを解説 | We.Inc

Docker Composeのenv_file、environment、.envファイルそれぞれの役割、値が競合したときの優先順位、${VAR:-default}の変数展開の仕組みを解説。判定ツール付き。

Docker Composeでは、env_fileはKEY=value形式の行が並んだファイルを1つのサービスのコンテナに読み込みます。environment属性はコンテナの変数をインラインで設定し、同じキーがあればenv_fileより優先されます。compose.yamlの横にある.envファイルは別物で、ComposeがYAML自体の${VAR}プレースホルダーを埋めるために読み込みます。

Composeに変数を渡す3つの方法

仕組み
適用範囲
コンテナに届くか

compose.yamlの横の.env
Composeファイル内の${VAR}の展開
サービスが参照した場合のみ

サービスのenv_file:
そのサービスのコンテナ
届く。すべての行

サービスのenvironment:
そのサービスのコンテナ
届く。env_fileより優先

CLIの--env-file
展開に使うデフォルトの.envを置き換える
参照された場合のみ

混乱の原因は名前です。.envというファイルとenv_fileという属性は同じもののように聞こえますが、一方はComposeファイルを、もう一方はコンテナを設定します。判定ツールで変数にどのソースの値が採用されるかを確認し、変数が設定済み、空、未設定の場合に各展開形式がどうなるかを試してみましょう。

変数が設定されている場所にチェックを入れ、そこでの値を入力します。
判定ツールがDockerのドキュメントにある優先順位を上から順にたどり、コンテナに最終的に入る値を表示します。
展開のボックスで${VAR:-default}などの形式を選び、VARが設定済み、空、未設定のどれかを選んで結果を確認します。
プロジェクトでdocker compose configを実行し、Composeが実際に解決した内容を確認します。

docker compose config --environmentを実行すると、Composeが展開に使った変数が表示されます。たいていの議論は数秒で決着します。
任意のenvファイルにはrequired: false（Compose 2.24.0以降）を付けましょう。ローカルの上書きファイルがなくてもスタックが止まりません。
compose.yamlでドル記号そのものが必要なときは$$と書きます。パスワードやシェルコマンドなどで使います。
environmentのマップでは、SHOW: "true"のように真偽値を引用符で囲みましょう。YAMLが真偽値として解釈してしまうのを防げます。

よくある質問

env_fileとenvironmentの違いは何ですか？

どちらもサービスのコンテナに変数を入れます。env_fileは1つ以上のファイルから読み込み、environmentはcompose.yamlに直接列挙します。同じキーが両方にある場合は、たとえ値が空であっても後者の値が優先されます。

Composeは.envファイルを自動でコンテナに渡しますか？

渡しません。プロジェクトの.envファイルは、Composeファイル内の${VAR}を置き換えるためだけに使われます。変数がコンテナに届くのは、サービスがenvironmentでその名前を指定するか、env_fileでファイルを読み込んだ場合だけです。

Composeは.envファイルをどこで探しますか？

プロジェクトディレクトリです。これは--project-directoryで指定したフォルダー、なければ最初の-fファイルのフォルダー、それもなければ現在のフォルダーです。別のファイルを指定するには--env-fileを使います。複数指定した場合は、後のファイルが前のファイルを上書きします。

env_fileのパスはコマンドを実行した場所からの相対パスですか？

いいえ。env_fileの相対パスはComposeファイルがあるフォルダーを基準に解決されるため、どこから起動してもスタックは動作します。

VARが設定されていないとき、${VAR}はどうなりますか？

Composeは警告を表示し、空文字列で置き換えます。デフォルト値を指定するには${VAR:-fallback}を、エラーで停止させるには${VAR:?message}を使います。

優先順位の一覧（上から順に）

Dockerのドキュメントには5つのレベルがあります。最も強いのはdocker compose run -eで渡した値です。次に、シェルや環境ファイルから展開された値を持つenvironmentまたはenv_file、その次に前者に直接書かれた値、その次に後者のファイルから読み込んだ値、最後にイメージに組み込まれたENV行です。
このうち.envファイルに関係するのは1つだけで、それも間接的です。展開を通じて2番目のレベルに値を供給します。.envにあってもどのサービスも参照していない値は、コンテナ内には現れません。

値のないキー

environmentに等号なしで名前だけ（例：- API_TOKEN）を書くと、Composeを実行しているシェルから値がコピーされます。シェルにその変数がなければ、未設定のままになります。
env_fileでキーだけの行を書くと、その変数は未設定になりコンテナの環境から削除されます。イメージが設定した値を意図的に消したいときに便利です。

すべての展開形式

VARが設定済み、空、未設定の場合に各形式が返す値

形式
VAR=abc
VARが空
VARが未設定

${VAR}または$VAR
空、警告あり

${VAR:-default}

${VAR-default}

${VAR:?msg}
エラー msg
エラー msg

${VAR?msg}
エラー msg

${VAR:+other}

${VAR+other}

$そのもの
$そのもの
$そのもの

コピーして使えるComposeファイル

env_fileとenvironmentによる上書き

共通の設定はファイルから読み込み、environmentに書いたキーはその値が優先されます。ローカル用のファイルは任意です。

展開専用のプロジェクト.env

この2つの値はcompose.yamlのプレースホルダーを埋めます。サービスが参照しない限り、どちらもコンテナには届きません。

compose.yamlでその値を使う

イメージのタグと公開ポートは.envから取得します。パスワードは必須で、未設定ならComposeはわかりやすいメッセージとともに停止します。

Composeが解決した内容を確認する

このコマンドはすべての変数を埋めた最終的なモデルを表示し、--environmentを付けると置き換えに使われた値を一覧表示します。

どの値が採用される？

変数APP_MODEは、下でチェックした場所で設定されています。

変数が設定されている場所

値

コンテナに入る値はAPP_MODE={v}、設定元：{n}

どこにも設定されていないため、コンテナにAPP_MODEは存在しません。

展開テスター

式

VARの状態

設定済みだが空

VARの値

結果：{v}

結果：空文字列

Composeは次のエラーで停止します：{v}

結果：空文字列。Composeは警告を表示します

無料で始める · クレジットカード不要

製品

AI ホームページ作成ツール：作りたいサイトを普段の言葉で伝えるだけで、数分で公開
ホワイトラベルプラットフォーム：自社ブランド、自社ドメイン、自社の利益で運営
エンタープライズ：SSO、個別の SLA、専任サポート
開発者向け API：自社の SaaS にサイト生成機能を組み込み

ご利用いただける方

制作会社・代理店向け：自社ブランドで再販
フリーランス向け：自分ブランドのビルダーを持つ
ホスティング事業者向け：サービスにビルダーを追加
SaaS プラットフォーム向け：API でサイト作成を組み込み
スタートアップ向け
金融サービス向け
医療・ヘルスケア向け

機能

リソース

会社情報

サイトマップを見る

Docker Composeのenv_file、environment、.envの違い

Docker Compose env_fileガイド