path: root/devdocs/docker/compose%2Fenvironment-variables%2Findex.html

<h1>Environment variables in Compose</h1>

<p>There are multiple parts of Compose that deal with environment variables in one sense or another. This page should help you find the information you need.</p> <h2 id="substitute-environment-variables-in-compose-files">Substitute environment variables in Compose files</h2> <p>It’s possible to use environment variables in your shell to populate values inside a Compose file:</p> <div class="highlight"><pre class="highlight" data-language="">web:
  image: "webapp:${TAG}"
</pre></div> <p>If you have multiple environment variables, you can substitute them by adding them to a default environment variable file named <code class="language-plaintext highlighter-rouge">.env</code> or by providing a path to your environment variables file using the <code class="language-plaintext highlighter-rouge">--env-file</code> command line option.</p> <p>Your configuration options can contain environment variables. Compose uses the variable values from the shell environment in which <code class="language-plaintext highlighter-rouge">docker-compose</code> is run. For example, suppose the shell contains <code class="language-plaintext highlighter-rouge">POSTGRES_VERSION=9.3</code> and you supply this configuration:</p> <div class="highlight"><pre class="highlight" data-language="">db:
  image: "postgres:${POSTGRES_VERSION}"
</pre></div> <p>When you run <code class="language-plaintext highlighter-rouge">docker-compose up</code> with this configuration, Compose looks for the <code class="language-plaintext highlighter-rouge">POSTGRES_VERSION</code> environment variable in the shell and substitutes its value in. For this example, Compose resolves the <code class="language-plaintext highlighter-rouge">image</code> to <code class="language-plaintext highlighter-rouge">postgres:9.3</code> before running the configuration.</p> <p>If an environment variable is not set, Compose substitutes with an empty string. In the example above, if <code class="language-plaintext highlighter-rouge">POSTGRES_VERSION</code> is not set, the value for the <code class="language-plaintext highlighter-rouge">image</code> option is <code class="language-plaintext highlighter-rouge">postgres:</code>.</p> <p>You can set default values for environment variables using a <a href="../env-file/index"><code class="language-plaintext highlighter-rouge">.env</code> file</a>, which Compose automatically looks for in project directory (parent folder of your Compose file). Values set in the shell environment override those set in the <code class="language-plaintext highlighter-rouge">.env</code> file.</p> <blockquote class="important"> <p>Note when using docker stack deploy</p> <p>The <code class="language-plaintext highlighter-rouge">.env file</code> feature only works when you use the <code class="language-plaintext highlighter-rouge">docker-compose up</code> command and does not work with <code class="language-plaintext highlighter-rouge">docker stack deploy</code>.</p> </blockquote> <p>Both <code class="language-plaintext highlighter-rouge">$VARIABLE</code> and <code class="language-plaintext highlighter-rouge">${VARIABLE}</code> syntax are supported. Additionally when using the <a href="../compose-file/compose-versioning/index#version-21">2.1 file format</a>, it is possible to provide inline default values using typical shell syntax:</p> <ul> <li>
<code class="language-plaintext highlighter-rouge">${VARIABLE:-default}</code> evaluates to <code class="language-plaintext highlighter-rouge">default</code> if <code class="language-plaintext highlighter-rouge">VARIABLE</code> is unset or empty in the environment.</li> <li>
<code class="language-plaintext highlighter-rouge">${VARIABLE-default}</code> evaluates to <code class="language-plaintext highlighter-rouge">default</code> only if <code class="language-plaintext highlighter-rouge">VARIABLE</code> is unset in the environment.</li> </ul> <p>Similarly, the following syntax allows you to specify mandatory variables:</p> <ul> <li>
<code class="language-plaintext highlighter-rouge">${VARIABLE:?err}</code> exits with an error message containing <code class="language-plaintext highlighter-rouge">err</code> if <code class="language-plaintext highlighter-rouge">VARIABLE</code> is unset or empty in the environment.</li> <li>
<code class="language-plaintext highlighter-rouge">${VARIABLE?err}</code> exits with an error message containing <code class="language-plaintext highlighter-rouge">err</code> if <code class="language-plaintext highlighter-rouge">VARIABLE</code> is unset in the environment.</li> </ul> <p>Other extended shell-style features, such as <code class="language-plaintext highlighter-rouge">${VARIABLE/foo/bar}</code>, are not supported.</p> <p>You can use a <code class="language-plaintext highlighter-rouge">$$</code> (double-dollar sign) when your configuration needs a literal dollar sign. This also prevents Compose from interpolating a value, so a <code class="language-plaintext highlighter-rouge">$$</code> allows you to refer to environment variables that you don’t want processed by Compose.</p> <div class="highlight"><pre class="highlight" data-language="">web:
  build: .
  command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"
</pre></div> <p>If you forget and use a single dollar sign (<code class="language-plaintext highlighter-rouge">$</code>), Compose interprets the value as an environment variable and warns you:</p> <div class="highlight"><pre class="highlight" data-language="">The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string.
</pre></div> <h3 id="the-env-file">The “.env” file</h3> <p>You can set default values for any environment variables referenced in the Compose file, or used to configure Compose, in an <a href="../env-file/index">environment file</a> named <code class="language-plaintext highlighter-rouge">.env</code>. The <code class="language-plaintext highlighter-rouge">.env</code> file path is as follows:</p> <ul> <li>Starting with <code class="language-plaintext highlighter-rouge">+v1.28</code>, <code class="language-plaintext highlighter-rouge">.env</code> file is placed at the base of the project directory</li> <li>Project directory can be explicitly defined with the <code class="language-plaintext highlighter-rouge">--file</code> option or <code class="language-plaintext highlighter-rouge">COMPOSE_FILE</code> environment variable. Otherwise, it is the current working directory where the <code class="language-plaintext highlighter-rouge">docker compose</code> command is executed (<code class="language-plaintext highlighter-rouge">+1.28</code>).</li> <li>For previous versions, it might have trouble resolving <code class="language-plaintext highlighter-rouge">.env</code> file with <code class="language-plaintext highlighter-rouge">--file</code> or <code class="language-plaintext highlighter-rouge">COMPOSE_FILE</code>. To work around it, it is recommended to use <code class="language-plaintext highlighter-rouge">--project-directory</code>, which overrides the path for the <code class="language-plaintext highlighter-rouge">.env</code> file. This inconsistency is addressed in <code class="language-plaintext highlighter-rouge">+v1.28</code> by limiting the filepath to the project directory.</li> </ul> <div class="highlight"><pre class="highlight" data-language="">$ cat .env
TAG=v1.5

$ cat docker-compose.yml
version: '3'
services:
  web:
    image: "webapp:${TAG}"
</pre></div> <p>When you run <code class="language-plaintext highlighter-rouge">docker-compose up</code>, the <code class="language-plaintext highlighter-rouge">web</code> service defined above uses the image <code class="language-plaintext highlighter-rouge">webapp:v1.5</code>. You can verify this with the <a href="../reference/config/index">config command</a>, which prints your resolved application config to the terminal:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker-compose config

version: '3'
services:
  web:
    image: 'webapp:v1.5'
</pre></div> <p>Values in the shell take precedence over those specified in the <code class="language-plaintext highlighter-rouge">.env</code> file.</p> <p>If you set <code class="language-plaintext highlighter-rouge">TAG</code> to a different value in your shell, the substitution in <code class="language-plaintext highlighter-rouge">image</code> uses that instead:</p> <div class="highlight"><pre class="highlight" data-language="">$ export TAG=v2.0
$ docker-compose config

version: '3'
services:
  web:
    image: 'webapp:v2.0'
</pre></div> <p>You can override the environment file path using a command line argument <code class="language-plaintext highlighter-rouge">--env-file</code>.</p> <h3 id="using-the---env-file--option">Using the “--env-file” option</h3> <p>By passing the file as an argument, you can store it anywhere and name it appropriately, for example, <code class="language-plaintext highlighter-rouge">.env.ci</code>, <code class="language-plaintext highlighter-rouge">.env.dev</code>, <code class="language-plaintext highlighter-rouge">.env.prod</code>. Passing the file path is done using the <code class="language-plaintext highlighter-rouge">--env-file</code> option:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker-compose --env-file ./config/.env.dev up 
</pre></div> <p>This file path is relative to the current working directory where the Docker Compose command is executed.</p> <div class="highlight"><pre class="highlight" data-language="">$ cat .env
TAG=v1.5

$ cat ./config/.env.dev
TAG=v1.6


$ cat docker-compose.yml
version: '3'
services:
  web:
    image: "webapp:${TAG}"
</pre></div> <p>The <code class="language-plaintext highlighter-rouge">.env</code> file is loaded by default:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker-compose config 
version: '3'
services:
  web:
    image: 'webapp:v1.5'
</pre></div> <p>Passing the <code class="language-plaintext highlighter-rouge">--env-file</code> argument overrides the default file path:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker-compose --env-file ./config/.env.dev config 
version: '3'
services:
  web:
    image: 'webapp:v1.6'
</pre></div> <p>When an invalid file path is being passed as <code class="language-plaintext highlighter-rouge">--env-file</code> argument, Compose returns an error:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker-compose --env-file ./doesnotexist/.env.dev  config
ERROR: Couldn't find env file: /home/user/./doesnotexist/.env.dev
</pre></div> <p>For more information, see the <a href="../compose-file/compose-file-v3/index#variable-substitution">Variable substitution</a> section in the Compose file reference.</p> <h2 id="set-environment-variables-in-containers">Set environment variables in containers</h2> <p>You can set environment variables in a service’s containers with the <a href="../compose-file/compose-file-v3/index#environment">‘environment’ key</a>, just like with <code class="language-plaintext highlighter-rouge">docker run -e VARIABLE=VALUE ...</code>:</p> <div class="highlight"><pre class="highlight" data-language="">web:
  environment:
    - DEBUG=1
</pre></div> <h2 id="pass-environment-variables-to-containers">Pass environment variables to containers</h2> <p>You can pass environment variables from your shell straight through to a service’s containers with the <a href="../compose-file/compose-file-v3/index#environment">‘environment’ key</a> by not giving them a value, just like with <code class="language-plaintext highlighter-rouge">docker run -e VARIABLE ...</code>:</p> <div class="highlight"><pre class="highlight" data-language="">web:
  environment:
    - DEBUG
</pre></div> <p>The value of the <code class="language-plaintext highlighter-rouge">DEBUG</code> variable in the container is taken from the value for the same variable in the shell in which Compose is run.</p> <h2 id="the-env_file-configuration-option">The “env_file” configuration option</h2> <p>You can pass multiple environment variables from an external file through to a service’s containers with the <a href="../compose-file/compose-file-v3/index#env_file">‘env_file’ option</a>, just like with <code class="language-plaintext highlighter-rouge">docker run --env-file=FILE ...</code>:</p> <div class="highlight"><pre class="highlight" data-language="">web:
  env_file:
    - web-variables.env
</pre></div> <h2 id="set-environment-variables-with-docker-compose-run">Set environment variables with ‘docker-compose run’</h2> <p>Similar to <code class="language-plaintext highlighter-rouge">docker run -e</code>, you can set environment variables on a one-off container with <code class="language-plaintext highlighter-rouge">docker-compose run -e</code>:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker-compose run -e DEBUG=1 web python console.py
</pre></div> <p>You can also pass a variable from the shell by not giving it a value:</p> <div class="highlight"><pre class="highlight" data-language="">$ docker-compose run -e DEBUG web python console.py
</pre></div> <p>The value of the <code class="language-plaintext highlighter-rouge">DEBUG</code> variable in the container is taken from the value for the same variable in the shell in which Compose is run.</p> <p>When you set the same environment variable in multiple files, here’s the priority used by Compose to choose which value to use:</p> <ol> <li>Compose file</li> <li>Shell environment variables</li> <li>Environment file</li> <li>Dockerfile</li> <li>Variable is not defined</li> </ol> <p>In the example below, we set the same environment variable on an Environment file, and the Compose file:</p> <div class="highlight"><pre class="highlight" data-language="">$ cat ./Docker/api/api.env
NODE_ENV=test

$ cat docker-compose.yml
version: '3'
services:
  api:
    image: 'node:6-alpine'
    env_file:
     - ./Docker/api/api.env
    environment:
     - NODE_ENV=production
</pre></div> <p>When you run the container, the environment variable defined in the Compose file takes precedence.</p> <div class="highlight"><pre class="highlight" data-language="">$ docker-compose exec api node

&gt; process.env.NODE_ENV
'production'
</pre></div> <p>Having any <code class="language-plaintext highlighter-rouge">ARG</code> or <code class="language-plaintext highlighter-rouge">ENV</code> setting in a <code class="language-plaintext highlighter-rouge">Dockerfile</code> evaluates only if there is no Docker Compose entry for <code class="language-plaintext highlighter-rouge">environment</code> or <code class="language-plaintext highlighter-rouge">env_file</code>.</p> <blockquote> <p>Specifics for NodeJS containers</p> <p>If you have a <code class="language-plaintext highlighter-rouge">package.json</code> entry for <code class="language-plaintext highlighter-rouge">script:start</code> like <code class="language-plaintext highlighter-rouge">NODE_ENV=test node server.js</code>, then this overrules any setting in your <code class="language-plaintext highlighter-rouge">docker-compose.yml</code> file.</p> </blockquote> <h2 id="configure-compose-using-environment-variables">Configure Compose using environment variables</h2> <p>Several environment variables are available for you to configure the Docker Compose command-line behavior. They begin with <code class="language-plaintext highlighter-rouge">COMPOSE_</code> or <code class="language-plaintext highlighter-rouge">DOCKER_</code>, and are documented in <a href="../reference/envvars/index">CLI Environment Variables</a>.</p> 
<p><a href="https://docs.docker.com/search/?q=compose">compose</a>, <a href="https://docs.docker.com/search/?q=orchestration">orchestration</a>, <a href="https://docs.docker.com/search/?q=environment">environment</a>, <a href="https://docs.docker.com/search/?q=env%20file">env file</a></p>
<div class="_attribution">
  <p class="_attribution-p">
    &copy; 2019 Docker, Inc.<br>Licensed under the Apache License, Version 2.0.<br>Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.<br>Docker, Inc. and other parties may also have trademark rights in other terms used herein.<br>
    <a href="https://docs.docker.com/compose/environment-variables/" class="_attribution-link">https://docs.docker.com/compose/environment-variables/</a>
  </p>
</div>