How To Use An .env File In Docker Compose

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 .env located in the root directory of your project:

# .env

VERSION=v1.5

These variables can then be referenced in the compose.yaml file using the variable substitution syntax as follows:

# compose.yaml

version: '3'

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

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

Using custom .env files

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

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

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

Where:

• file 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 compose.yaml file and substitute the values of the environment variables from the .env.dev file.

Understanding the order of precedence of environment variables

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

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 .env file: The environment variables loaded using the --env-file flag takes precedence over the default .env file located at the root of your project's directory.
3. Default .env file: The variables set in the default .env file have the lowest precedence compared to the above sources.

Passing environment variables to services

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

environment:
  <name>:  ${VARIABLE}

Where:

• name specifies the name of the environment variable for the container.
• VARIABLE specifies the name of the environment variable defined in the .env 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 docker compose up command, Compose will start the web service and substitute the value of variables PG\_USERNAME, PG\_PASSWORD, and PG\_DATABASE with the values defined in the .env file.

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

Easily retrieve this syntax using Warp AI feature

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

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

Passing .env files to services

In Compose, to pass an entire environment file to a service listed in the compose.yaml file, you the env\_file property as follows:

env_file:
  - <file>

Where:

• file 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 docker compose up command, Compose will start the web service and forward all the environment variables defined in the .env.dev and .env.prod 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 environment have a higher precedence than the ones passed under the env\_file property.

Defining default values for environment variables

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:

• ${VAR:-default} is used to indicate that the default value should be used when the variable VAR is empty or unset.
• ${VAR-default} is used to indicate that the default value should be used only when the variable VAR 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 docker-compose up command, the environment variables will be set as follows:

• NGINX\_VERSION is set and non-empty in the .env file, so the specified value 1.19.5 will be used.
• DB\_URL is not set in the .env file, so the default value mysql://user:password@dbhost/dbname will be used.
• CONTAINER\_PORT is set but is empty in the .env file, so the default value 8080 will be used.

Enforcing required values for environment variables

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:

• ${VAR:?error} will exit with the specified error message error if the variable VAR is empty or unset.
• ${VAR?error} will exit with the specified error message error only if the variable VAR 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 docker-compose up command, the environment variables will be set as follows:

• TAG is set and non-empty in the .env file, so the specified value v1.5 will be used.
• API\_KEY is not set in the .env file, so the command will exit with the error message Error: API\_KEY is required.
• CONTAINER\_PORT is set but is empty in the .env file.
• With the colon (:) syntax, the empty value for the CONTAINER\_PORT will be used.
• Without the colon (:) syntax, the command will not exit, and the empty value for the CONTAINER\_PORT will be used.

Replacing environment 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:

• ${VAR:+replacement} replaces the value of the VAR variable with replacement if the variable is set and non-empty.
• ${VAR+replacement} replaces the value of the VAR variable with replacement 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 docker-compose up command, the environment variables will be set as follows:

• TAG is set and non-empty in the .env file, so the replacement value latest will be used.
• DB\_URL is not set in the .env file, so an empty value will be used for DB\_URL.
• CONTAINER\_PORT is set but empty in the .env file.
• With the colon (:) syntax, the empty value for the CONTAINER\_PORT will be used.
• Without the colon (:) syntax, the replacement value 8080 will be used.