docsCreated with Sketch.

Use an environment file in Docker 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 compose.yml file. For more information, see Environment variables precedence.