Use an environment file

Important

From the end of June 2023 Compose V1 won’t be supported anymore and will be removed from all Docker Desktop versions.

Make sure you switch to Compose V2 with the docker compose CLI plugin or by activating the Use Docker Compose V2 setting in Docker Desktop. For more information, see the Evolution of Compose

Syntax

The following syntax rules apply to environment files:

  • Lines beginning with # are processed as comments and ignored.
  • Blank lines are ignored.
  • Unquoted and double-quoted (") values have parameter expansion applied.
  • Each line represents a key-value pair. Values can optionally be quoted.
    • VAR=VAL -> VAL
    • VAR="VAL" -> VAL
    • VAR='VAL' -> VAL
  • Inline comments for unquoted values must be preceded with a space.
    • VAR=VAL # comment -> VAL
    • VAR=VAL# not a comment -> VAL# not a comment
  • Inline comments for quoted values must follow the closing quote.
    • VAR="VAL # not a comment" -> VAL # not a comment
    • VAR="VAL" # comment -> VAL
  • Single-quoted (') values are used literally.
    • VAR='$OTHER' -> $OTHER
    • VAR='${OTHER}' -> ${OTHER}
  • Quotes can be escaped with \.
    • VAR='Let\'s go!' -> Let's go!
    • VAR="{\"hello\": \"json\"}" -> {"hello": "json"}
  • Common shell escape sequences including \n, \r, \t, and \\ are supported in double-quoted values.
    • VAR="some\tvalue" -> some value
    • VAR='some\tvalue' -> some\tvalue
    • VAR=some\tvalue -> some\tvalue

Parameter Expansion

Compose supports parameter expansion in environment files. Parameter expansion is applied for unquoted and double-quoted values. Both braced (${VAR}) and unbraced ($VAR) expressions are supported.

For braced expressions, the following formats are supported:

  • Direct substitution
    • ${VAR} -> value of VAR
  • Default value
    • ${VAR:-default} -> value of VAR if set and non-empty, otherwise default
    • ${VAR-default} -> value of VAR if set, otherwise default
  • Required value
    • ${VAR:?error} -> value of VAR if set and non-empty, otherwise exit with error
    • ${VAR?error} -> value of VAR if set, otherwise exit with error
  • Alternative value
    • ${VAR:+replacement} -> replacement if VAR is set and non-empty, otherwise empty
    • ${VAR+replacement} -> replacement if VAR is set, otherwise empty

Precedence

Environment variables from an environment file have lower precedence than those passed via the command-line or via the environment attribute in the docker-compose.yml file. For more information, see Environment variables precedence.