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

Run in Warp

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}"

Run in Warp

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 

Run in Warp

Where:

• file is the absolute or relative path to the environment file.

For example:

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

Run in Warp

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. 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. 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. 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}

Run in Warp

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"

Run in Warp

 # 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

Run in Warp

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>

Run in Warp

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

Run in Warp

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}

Run in Warp

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=

Run in Warp

 # 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}

Run in Warp

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}

Run in Warp

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=

Run in Warp

 # 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}

Run in Warp

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}

Run in Warp

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=

Run in Warp

# 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}

Run in Warp

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.