Ways to set environment variables in Compose
Important
From the end of June 2023 Compose V1 won’t be supported anymore and will be removed from all Docker Desktop versions.
Make sure you switch to Compose V2 with the
docker compose
CLI plugin or by activating the Use Docker Compose V2 setting in Docker Desktop. For more information, see the Evolution of Compose
Environment variables are dealt with by either the Compose file or the CLI. Both have multiple ways you can substitute in or set, your environment variables. This is outlined below.
Compose file
Substitute with an .env
file
The .env
file is useful if you have multiple environment variables you need to store.
Below is a simple example:
$ cat .env
TAG=v1.5
$ cat docker-compose.yml
services:
web:
image: "webapp:${TAG}"
When you run docker compose up
, the web
service defined in the Compose file substitues in the
image webapp:v1.5
which was set in the .env
file. You can verify this with the
config command, which prints your resolved application config to the terminal:
$ docker compose config
services:
web:
image: 'webapp:v1.5'
The .env
file should be placed at the root of the project directory next to your docker-compose.yml
file. You can use an alternative path with one of the following methods:
- The
--file
option in the CLI - The
--env-file
option in the CLI - Using the
env_file
attribute in the Compose file
For more information on formatting an environment file, see Use an environment file.
Important
Substitution from
.env
files is a Docker Compose CLI feature.It is not supported by Swarm when running
docker stack deploy
.
Use the environment
attribute
You can set environment variables in a service’s containers with the
environment
attribute in your Compose file. It works in the same way as docker run -e VARIABLE=VALUE ...
web:
environment:
- DEBUG=1
You can choose not to set a value and pass the environment variables from your shell straight through to a
service’s containers. It works in the same way as docker run -e VARIABLE ...
:
web:
environment:
- DEBUG
The value of the DEBUG
variable in the container is taken from the value for the same variable in the shell in which Compose is run.
See environment
attribute for more information.
Use the env_file
attribute
You can pass multiple environment variables from an external file through to
a service’s containers with the env_file
option. This works in the same way as docker run --env-file=FILE ...
:
web:
env_file:
- web-variables.env
If multiple files are specified, they are evaluated in order and can override values set in previous files.
Note
With this option, environment variables declared in the file cannot then be referenced again separately in the Compose file or used to configure Compose.
See env_file
attribute for more information.
Substitute from the shell
It’s possible to use environment variables in your shell to populate values inside a Compose file. Compose uses the variable values from the shell environment in which docker compose
is run.
For example, suppose the shell contains POSTGRES_VERSION=9.3
and you supply the following configuration:
db:
image: "postgres:${POSTGRES_VERSION}"
When you run docker compose up
with this configuration, Compose looks for the POSTGRES_VERSION
environment variable in the shell and substitutes its value in. For this example, Compose resolves the image to postgres:9.3
before running the configuration.
If an environment variable is not set, Compose substitutes with an empty string. In the example above, if POSTGRES_VERSION
is not set, the value for the image option is postgres:.
Important
Values set in the shell environment override those set in the
.env
file, theenvironment
attribute, and theenv_file
attribute. For more information, see Environment variable precedence.
CLI
Substitute with --env-file
You can set default values for multiple environment variables, in an environment file and then pass the file as an argument in the CLI.
The advantage of this method is that you can store the file anywhere and name it appropriately, for example, .env.ci
, .env.dev
, .env.prod
. This file path is relative to the current working directory where the Docker Compose command is executed. Passing the file path is done using the --env-file
option:
$ docker compose --env-file ./config/.env.dev up
In the example below, there are two environment files, .env
and .env.dev
. Both have different values set for TAG
.
$ cat .env
TAG=v1.5
$ cat ./config/.env.dev
TAG=v1.6
$ cat docker-compose.yml
services:
web:
image: "webapp:${TAG}"
If the --env-file
is not used in the command line, the .env
file is loaded by default:
$ docker compose config
services:
web:
image: 'webapp:v1.5'
Passing the --env-file
argument overrides the default file path:
$ docker compose --env-file ./config/.env.dev config
services:
web:
image: 'webapp:v1.6'
When an invalid file path is being passed as an --env-file
argument, Compose returns an error:
$ docker compose --env-file ./doesnotexist/.env.dev config
ERROR: Couldn't find env file: /home/user/./doesnotexist/.env.dev
Important
Values set in the shell environment override those set when using the
--env-file
argument in the CLI. For more information, see Environment variable precedence
Set environment variables with docker compose run --env
Similar to docker run --env
, you can set environment variables in a one-off
container with docker compose run --env
or its short form docker compose run -e
:
$ docker compose run -e DEBUG=1 web python console.py
You can also pass a variable from the shell by not giving it a value:
$ docker compose run -e DEBUG web python console.py
The value of the DEBUG
variable in the container is taken from the value for
the same variable in the shell in which Compose is run.