Set environment variables within your container's environment

Table of contents

A container's environment is not set until there's an explicit entry in the service configuration to make this happen. With Compose, there are two ways you can set environment variables in your containers with your Compose file.

Tip

Don't use environment variables to pass sensitive information, such as passwords, in to your containers. Use secretsinstead.

Use theenvironmentattribute

You can set environment variables directly in your container's environment with the environmentattributein yourcompose.yml.

It supports both list and mapping syntax:

services:
webapp:
environment:
DEBUG:"true"

is equivalent to

services:
webapp:
environment:
-DEBUG=true

See environmentattributefor more examples on how to use it.

Additional information

  • You can choose not to set a value and pass the environment variables from your shell straight through to your containers. It works in the same way asdocker run -e VARIABLE...:
    web:
environment:
-DEBUG

The value of theDEBUGvariable in the container is taken from the value for the same variable in the shell in which Compose is run. Note that in this case no warning is issued if theDEBUGvariable in the shell environment is not set.

  • You can also take advantage of interpolation.In the following example, the result is similar to the one above but Compose gives you a warning if theDEBUGvariable is not set in the shell environment or in an.envfile in the project directory.

    web:
environment:
-DEBUG=${DEBUG}

Use theenv_fileattribute

A container's environment can also be set using .envfilesalong with the env_fileattribute.

services:
webapp:
env_file:"webapp.env"

Using an.envfile lets you use the same file for use by a plaindocker run --env-file...command, or to share the same.envfile within multiple services without the need to duplicate a longenvironmentYAML block.

It can also help you keep your environment variables separate from your main configuration file, providing a more organized and secure way to manage sensitive information, as you do not need to place your.envfile in the root of your project's directory.

The env_fileattributealso lets you use multiple.envfiles in your Compose application.

The paths to your.envfile, specified in theenv_fileattribute, are relative to the location of yourcompose.ymlfile.

Important

Interpolation in.envfiles is a Docker Compose CLI feature.

It is not supported when runningdocker run --env-file....

Additional information

  • If multiple files are specified, they are evaluated in order and can override values set in previous files.
  • As of Docker Compose version 2.24.0, you can set your.envfile, defined by theenv_fileattribute, to be optional by using therequiredfield. Whenrequiredis set tofalseand the.envfile is missing, Compose silently ignores the entry.
    env_file:
-path:./default.env
required:true# default
-path:./override.env
required:false
  • Values in your.envfile can be overridden from the command line by using docker compose run -e.

Set environment variables withdocker compose run --env

Similar todocker run --env,you can set environment variables temporarily withdocker compose run --envor its short formdocker compose run -e:

$docker compose run -eDEBUG=1web Python console.py

Additional information

  • You can also pass a variable from the shell or your environment files by not giving it a value:

    $docker compose run -e DEBUG web Python console.py

The value of theDEBUGvariable in the container is taken from the value for the same variable in the shell in which Compose is run or from the environment files.

Further resources