Terminus by Warp
How To Use An .env File In Docker Compose

How To Use An .env File In Docker Compose

 Mansi Manhas
Mansi Manhas

The short answer

In Docker Compose, environment variables can be defined in the form of a list of key-value pairs in a file named [.inline-code].env[.inline-code] located in the root directory of your project:

 # .env

VERSION=v1.5

These variables can then be referenced in the [.inline-code]compose.yaml[.inline-code] file using the variable substitution syntax as follows:

 # compose.yaml

version: '3'

services:
  web:
    image: "webapp:${VERSION}"

In this example, upon execution of the [.inline-code]docker compose up[.inline-code] command, Docker will substitute the [.inline-code]VERSION[.inline-code] variable with its value, resulting in the pulling of the [.inline-code]webapp:v1.5[.inline-code] image. Note that, if the specified environment variable is not set, Docker will substitute the variable with an empty string.

[#use-custom-env-files] Using custom [.inline-code].env[.inline-code] files [#use-custom-env-files]

Complex projects often include multiple environment files for different purposes, like development (e.g. [.inline-code].env.dev[.inline-code]) and production (e.g. [.inline-code].env.prod[.inline-code]).

In Compose, to use a specific environment file instead of the default [.inline-code].env[.inline-code] file, you can use the [.inline-code]docker compose up[.inline-code] command with the [.inline-code]--env-file[.inline-code] flag as follows: 

 $ docker compose --env-file <file> up 

Where:

  • [.inline-code]file[.inline-code] is the absolute or relative path to the environment file.

For example:

 $ docker-compose --env-file ./config/.env.dev up

Upon execution, the above command will bring up the services set in the [.inline-code]compose.yaml[.inline-code] file and substitute the values of the environment variables from the [.inline-code].env.dev[.inline-code] file.

[#understand-the-variable-precedence] Understanding the order of precedence of environment variables [#understand-the-variable-precedence]

In Compose, the same environment variables can be defined in multiple places, like the shell environment, the default [.inline-code].env[.inline-code] file, or an arbitrary environment file (e.g. [.inline-code].env.prod[.inline-code]).

The order of precedence of these variables is as follows, from the highest to the lowest:

  1. Shell environment: The variables set in your shell environment take the highest priority. Any variables set in the shell environment will always override those in your environment files. 
  2. Custom [.inline-code].env[.inline-code] file: The environment variables loaded using the [.inline-code]--env-file[.inline-code] flag takes precedence over the default [.inline-code].env[.inline-code] file located at the root of your project's directory. 
  3. Default [.inline-code].env[.inline-code] file: The variables set in the default [.inline-code].env[.inline-code] file have the lowest precedence compared to the above sources.

[#pass-environment-variables-to-containers] Passing environment variables to services [#pass-environment-variables-to-containers]

In Compose, to pass environment variables defined in the [.inline-code].env[.inline-code] file to the various services defined in the [.inline-code]compose.yaml[.inline-code] file, you can use the [.inline-code]environment[.inline-code] property as follows:

 environment:
  <name>:  ${VARIABLE}

Where:

  • [.inline-code]name[.inline-code] specifies the name of the environment variable for the container.
  • [.inline-code]VARIABLE[.inline-code] specifies the name of the environment variable defined in the [.inline-code].env[.inline-code] file.

For example:

 # .env

PG_USERNAME="admin"
PG_PASSWORD="superadmin"
PG_DATABASE="shop"
 # compose.yaml

version: '3'

services:
  db:
    image: postgres
    environment:
      POSTGRES_USER: ${PG_USERNAME}
      POSTGRES_PASSWORD: ${PG_PASSWORD}
      POSTGRES_DB: ${PG_DATABASE}
    volumes:
      - ./data:/var/lib/postgresql/data
    ports:
      - 5432:5432

Upon execution of the [.inline-code]docker compose up[.inline-code] command, Compose will start the [.inline-code]web[.inline-code] service and substitute the value of variables [.inline-code]PG_USERNAME[.inline-code], [.inline-code]PG_PASSWORD[.inline-code], and [.inline-code]PG_DATABASE[.inline-code] with the values defined in the [.inline-code].env[.inline-code] file.

You can learn more about PostgreSQL with our article on how to launch a PostgreSQL instance using Docker Compose.

[#easily-recall-syntax-with-ai] Easily retrieve this syntax using Warp AI feature [#easily-recall-syntax-with-ai]

If you’re using Warp as your terminal, you can easily retrieve this syntax using the Warp AI feature:

Entering [.inline-code]docker compose env file[.inline-code] in the AI question input will prompt a human-readable step by step guide including code snippets.

Passing [.inline-code].env[.inline-code] files to services

In Compose, to pass an entire environment file to a service listed in the [.inline-code]compose.yaml[.inline-code] file, you the [.inline-code]env_file[.inline-code] property as follows:

 env_file:
  - <file>

Where:

  • [.inline-code]file[.inline-code] is the absolute or relative path to the environment file.

For example:

 # compose.yaml

version: '3'

services:
  web:
    build: .
    env_file:
     - ./.env.dev
     - ./.env.prod

Upon execution of the [.inline-code]docker compose up[.inline-code] command, Compose will start the [.inline-code]web[.inline-code] service and forward all the environment variables defined in the [.inline-code].env.dev[.inline-code] and [.inline-code].env.prod[.inline-code] files.

Note that since environment files are loaded sequentially, some variables may potentially be overwritten if already defined in preceding files.

Also note that environment variables defined under the [.inline-code]environment[.inline-code] have a higher precedence than the ones passed under the [.inline-code]env_file[.inline-code] property.

[#define-default-variable-values] Defining default values for environment variables [#define-default-variable-values]

In Compose, to assign a default fallback value to an unset or empty environment variable, you can use either one of the following variable substitution expressions:

 ${VAR:-default}
${VAR-default}

Where:

  • [.inline-code]${VAR:-default}[.inline-code] is used to indicate that the [.inline-code]default[.inline-code] value should be used when the variable [.inline-code]VAR[.inline-code] is empty or unset. 
  • [.inline-code]${VAR-default}[.inline-code] is used to indicate that the [.inline-code]default[.inline-code] value should be used only when the variable [.inline-code]VAR[.inline-code] is not set.

For example:

 # .env
NGINX_VERSION=1.19.5
CONTAINER_PORT=
 # compose.yaml

version: '3'

services:
  web:
    image: "nginx:${NGINX_VERSION:-latest}"
    environment:
      - DATABASE_URL=${DB_URL:-mysql://user:password@dbhost/dbname}
    ports:
      - ${CONTAINER_PORT:-8080}

Upon execution of the [.inline-code]docker-compose up[.inline-code] command, the environment variables will be set as follows:

  • [.inline-code]NGINX_VERSION[.inline-code] is set and non-empty in the [.inline-code].env[.inline-code] file, so the specified value [.inline-code]1.19.5[.inline-code] will be used.
  • [.inline-code]DB_URL[.inline-code] is not set in the [.inline-code].env[.inline-code] file, so the default value [.inline-code]mysql://user:password@dbhost/dbname[.inline-code] will be used.
  • [.inline-code]CONTAINER_PORT[.inline-code] is set but is empty in the [.inline-code].env[.inline-code] file, so the default value [.inline-code]8080[.inline-code] will be used.

[#enforce-required-variable-values] Enforcing required values for environment variables [#enforce-required-variable-values]

In Compose, to enforce the existence or definition of a required environment variable, which is essential for the proper functioning of the application, you can use either one of the following variable substitution expressions:

${VAR:?error}
${VAR?error}

Where:

  • [.inline-code]${VAR:?error}[.inline-code] will exit with the specified error message [.inline-code]error[.inline-code] if the variable [.inline-code]VAR[.inline-code] is empty or unset. 
  • [.inline-code]${VAR?error}[.inline-code] will exit with the specified error message [.inline-code]error[.inline-code] only if the variable [.inline-code]VAR[.inline-code] is not set.

For example: 

 # .env

TAG=v1.5
CONTAINER_PORT=
 # compose.yaml

version: '3'

services:
  web:
    image: "nginx:${TAG:?Error: TAG is required}"
    environment:
      - API_KEY=${API_KEY:?Error: API_KEY is required}
    ports:
      - ${CONTAINER_PORT:?Error: Container Port is required}
      - ${CONTAINER_PORT?Error: Container Port is required}

Upon execution of the [.inline-code]docker-compose up[.inline-code] command, the environment variables will be set as follows: 

  • [.inline-code]TAG[.inline-code] is set and non-empty in the .env file, so the specified value [.inline-code]v1.5[.inline-code] will be used. 
  • [.inline-code]API_KEY[.inline-code] is not set in the .env file, so the command will exit with the error message [.inline-code]Error: API_KEY is required[.inline-code]. 
  • [.inline-code]CONTAINER_PORT[.inline-code] is set but is empty in the .env file. 
  • With the colon ([.inline-code]:[.inline-code]) syntax, the empty value for the [.inline-code]CONTAINER_PORT[.inline-code] will be used. 
  • Without the colon ([.inline-code]:[.inline-code]) syntax, the command will not exit, and the empty value for the [.inline-code]CONTAINER_PORT[.inline-code] will be used.

[#replace-existing-variable-values] Replacing environment variable values [#replace-existing-variable-values]

In Compose, to allow your application to dynamically switch between different configurations based on the availability of specific values, you can overwrite the value of an existing or non-empty environment variable using either one of the following variable substitution expressions:

${VAR:+replacement}
${VAR+replacement}

Where:

  • [.inline-code]${VAR:+replacement}[.inline-code] replaces the value of the [.inline-code]VAR[.inline-code] variable with [.inline-code]replacement[.inline-code] if the variable is set and non-empty. 
  • [.inline-code]${VAR+replacement}[.inline-code] replaces the value of the [.inline-code]VAR[.inline-code] variable with [.inline-code]replacement[.inline-code] only if the variable is set. 

For example: 

 # .env

TAG=v1.5
CONTAINER_PORT=
# compose.yaml

version: '3'

services:
  web:
    image: "nginx:${TAG:+latest}"
    environment:
DB_URL=${DB_URL:+mysql://user:password@dbhost/dbname}
    ports:
      - ${CONTAINER_PORT:+8080}
      - ${CONTAINER_PORT+8080}

Upon execution of the [.inline-code]docker-compose up[.inline-code] command, the environment variables will be set as follows:

  • [.inline-code]TAG[.inline-code] is set and non-empty in the .env file, so the replacement value [.inline-code]latest[.inline-code] will be used.
  • [.inline-code]DB_URL[.inline-code] is not set in the .env file, so an empty value will be used for [.inline-code]DB_URL[.inline-code]. 
  • [.inline-code]CONTAINER_PORT[.inline-code] is set but empty in the .env file. 
  • With the colon ([.inline-code]:[.inline-code]) syntax, the empty value for the [.inline-code]CONTAINER_PORT[.inline-code] will be used. 
  • Without the colon ([.inline-code]:[.inline-code]) syntax, the replacement value [.inline-code]8080[.inline-code] will be used.

Experience the power of Warp

  • Write with an IDE-style editor
  • Easily navigate through output
  • Save commands to reuse later
  • Ask Warp AI to explain or debug
  • Customize keybindings and launch configs
  • Pick from preloaded themes or design your own
brew install --cask warp
Copied!
Join the Windows waitlist:
Success! You will receive an email from Warp when the release is available to download.
Oops! Something went wrong while submitting the form.
Join the Linux waitlist:
Success! You will receive an email from Warp when the release is available to download.
Oops! Something went wrong while submitting the form.
Join the Linux waitlist or join the Windows waitlist
Join the Windows waitlist:
Success! You will receive an email from Warp when the release is available to download.
Oops! Something went wrong while submitting the form.