Declare default environment variables in file

Estimated reading time: 3 minutes

Compose supports declaring environment variables in an environment file.

Syntax

The following syntax rules apply to environment files:

  • Each line represents a key-value pair. Values can optionally be quoted.
    • VAR=VAL -> VAL
    • VAR="VAL" -> VAL
    • VAR='VAL' -> VAL
  • Lines beginning with # are processed as comments and ignored.
  • Inline comments for unquoted values must be proceeded 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
  • Blank lines are ignored.
  • Unquoted and double-quoted (") values have parameter expansion applied.
  • 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 section in project YAML. Refer to Environment Variables Precedence for details.

Compose file and CLI variables

The environment variables you define here are used for variable substitution in your Compose file, and can also be used to define the following CLI variables:

  • COMPOSE_API_VERSION
  • COMPOSE_CONVERT_WINDOWS_PATHS
  • COMPOSE_FILE
  • COMPOSE_HTTP_TIMEOUT
  • COMPOSE_PROFILES
  • COMPOSE_PROJECT_NAME
  • COMPOSE_TLS_VERSION
  • DOCKER_CERT_PATH
  • DOCKER_HOST
  • DOCKER_TLS_VERIFY

Notes

  • Values present in the environment at runtime always override those defined inside the .env file. Similarly, values passed via command-line arguments take precedence as well.
  • Environment variables defined in the .env file are not automatically visible inside containers. To set container-applicable environment variables, follow the guidelines in the topic Environment variables in Compose, which describes how to pass shell environment variables through to containers, define environment variables in Compose files, and more.

More Compose documentation

fig, composition, compose, docker, orchestration, environment, env file