docs/compose/environment-variables.md

---
title: Environment variables in Compose
description: How to set, use and manage environment variables in Compose
keywords: compose, orchestration, environment, env file
---

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.


## Substitute environment variables in Compose files

It's possible to use environment variables in your shell to populate values
inside a Compose file:

```yaml
web:
  image: "webapp:${TAG}"
```

For more information, see the
[Variable substitution](compose-file.md#variable-substitution) section in the
Compose file reference.


## Set environment variables in containers

You can set environment variables in a service's containers with the
['environment' key](compose-file.md#environment), just like with
`docker run -e VARIABLE=VALUE ...`:

```yaml
web:
  environment:
    - DEBUG=1
```

## Pass environment variables to containers

You can pass environment variables from your shell straight through to a
service's containers with the ['environment' key](compose-file.md#environment)
by not giving them a value, just like with `docker run -e VARIABLE ...`:

```yaml
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.

## The “env_file” configuration option

You can pass multiple environment variables from an external file through to
a service's containers with the ['env_file' option](compose-file.md#envfile),
just like with `docker run --env-file=FILE ...`:

```yaml
web:
  env_file:
    - web-variables.env
```

## Set environment variables with 'docker-compose run'

Just like with `docker run -e`, you can set environment variables on a one-off
container with `docker-compose run -e`:

```bash
docker-compose run -e DEBUG=1 web python console.py
```

You can also pass a variable through from the shell by not giving it a value:

```bash
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.


## The “.env” file

You can set default values for any environment variables referenced in the
Compose file, or used to configure Compose, in an [environment file](env-file.md)
named `.env`:

```bash
$ cat .env
TAG=v1.5

$ cat docker-compose.yml
version: '3'
services:
  web:
    image: "webapp:${TAG}"
```

When you run `docker-compose up`, the `web` service defined above uses the
image `webapp:v1.5`. You can verify this with the
[config command](reference/config.md), which prints your resolved application
config to the terminal:

```bash
$ docker-compose config

version: '3'
services:
  web:
    image: 'webapp:v1.5'
```

Values in the shell take precedence over those specified in the `.env` file.
If you set `TAG` to a different value in your shell, the substitution in `image`
uses that instead:

```bash
$ export TAG=v2.0
$ docker-compose config

version: '3'
services:
  web:
    image: 'webapp:v2.0'
```

When you set the same environment variable in multiple files, here's the
priority used by Compose to choose which value to use:

1. Compose file,
2. Environment file,
3. Dockerfile,
4. Variable is not defined.

In the example below, we set the same environment variable on an Environment
file, and the Compose file:

```bash
$ 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
```

When you run the container, the environment variable defined in the Compose
file takes precedence.

```bash
$ docker-compose exec api node

> process.env.NODE_ENV
'production'
```

Having any `ARG` or `ENV` setting in a `Dockerfile` evaluates only if there is
no Docker Compose entry for `environment` or `env_file`.

> Specifics for NodeJS containers
>
> If you have a `package.json` entry for `script:start` like
> `NODE_ENV=test node server.js`, then this overrules any setting in your
> `docker-compose.yml` file.

## Configure Compose using environment variables

Several environment variables are available for you to configure the Docker
Compose command-line behavior. They begin with `COMPOSE_` or `DOCKER_`, and are
documented in [CLI Environment Variables](reference/envvars.md).

## Environment variables created by links

When using the ['links' option](compose-file.md#links) in a
[v1 Compose file](compose-file.md#version-1), environment variables are created
for each link. They are documented in
the [Link environment variables reference](link-env-deprecated.md).

However, these variables are deprecated. Use the link alias as a hostname instead.