Use An .env File In Docker

The short answer

In Docker, environment variables can be defined in a plain text file named .env, typically (but not necessarily) located in the root directory of your project, in the form of a list of key-value pairs:

VARIABLE=VALUE

Where:

• VARIABLE is the name of the environment variable.
• VALUE is the value assigned to that variable.

Once the .env file defined, you can start a new Docker container and load its variables into the container's environment using the docker run command with the --env-file flag as follows:

$ docker run --env-file <path> <image>

Where:

• path is the path to the .env file.
• image is the name of the base image the container will be launched from.

Note that since the .env file is supplied to the docker run command through the --env-file flag, it can be placed anywhere on the filesystem.

You can learn more about .env files in Compose by reading our other article on how to pass environment variables to services in Docker Compose.

The .env file syntax

To be valid, an .env file must follow a specific set of rules.

Variable names

Variable names must:

• Have a maximum length of 64 characters.
• Start with a letter ([a-zA-Z]) or an underscore character (_).

Variables can only contain:

• Lowercase and uppercase letters ([a-zA-Z]).
• Numbers ([1-9]).
• Underscores (_).

For example:

foobar
DATABASE_URL
_DB_HOST

Variable values

Values can:

• Be empty.
• Have a maximum length of 256 characters.
• Optionally be enclosed in single quotes or double quotes.

For example:

PASSWORD=
USERNAME=johndoe
API_KEY='HelloWorld1234'
DATABASE_URL="http://localhost:5432"

Comments

Any line beginning with # will be treated as a comment and will therefore be ignored.

For example:

# This will be ignored
USERNAME=johndoe

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 How to create and load an .env file in Docker? in the AI question input will prompt a human-readable step by step guide including code snippets.

Using an.envfile per environment

To facilitate the development and deployment of software applications with Docker, it is common practice to store your environment variables into multiple .env files with an explicit name referencing the environment they are intended for.

For example:

• .env.development
• .env.staging
• .env.production

This allows developers to easily manage and switch between configurations without altering the codebase, keep sensitive production credentials unexposed to testing environments, facilitate the software deployment through scripting, and prevent mistakes or unwanted changes in configuration.

For example:

$ docker run --env-file .env.development api-server-dev

Loading multiple.envfiles at once

In Docker, you can load several .env files at once, simply by repeating the --env-file flag multiple times:

$ docker run --env-file <path> [--env-file <path>] <image>

Note that if the same variable is defined multiple times in different .env files, its value will be overwritten by the value defined in the last specified .env file.

For example, let's consider the following .env files:

# .env.staging_1

DB_HOST="http://localhost:5432"
DB_USER="admin"
DB_PASSWORD="helloworld"

# .env.staging_2

DB_HOST="http://localhost:3306"

When launching the following container, the environment will contain all three variables DB_HOST, DB_USER, and DB_PASSWORD, however, the DB_HOST variable will hold the string "http://localhost:3306":

$ docker run --rm --env-file .env.staging_1 --env-file .env.staging_2 ubuntu env
DB_HOST="http://localhost:3306"
DB_USER="admin"
DB_PASSWORD="helloworld"

Unsupported features

Multi-line values

Docker doesn't currently support multi-line values and will only pick up on the first line.

For example, let's consider the following .env file:

PRIVATE_KEY="MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6Ppy1tPf9Cnzj4p4WGeKLs1Pt8Qu
KUpRKfFLfRYC9AIKjbJTWit+CqvjWYzvQwECAwEAAQJAIJLixBy2qpFoS4DSmoEm"

When launching the following container, the PRIVATE_KEY variable will only hold the first line of the value defined in the .env file:

$ docker run --rm --env-file .env ubuntu env | grep PRIVATE_KEY
PRIVATE_KEY="MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6Ppy1tPf9Cnzj4p4WGeKLs1Pt8Qu

Inline comments

In Docker, a # appearing at the end of a value will be treated as part of the value.

For example, let's consider the following .env file:

DB_USER="admin" # comment

When launching the following container, the DB_USER variable's value will also include the string # comment:

$ docker run --rm --env-file .env ubuntu env | grep DB_USER
DB_USER="admin" # comment

Interpolation

In Docker, the value of variables must be manually defined and cannot be copied from the local environment.

For example, let's consider the following .env file:

USERNAME=${USER}

When launching the following container, the USERNAME variable's value will be defined as the literal string "${USER}" and not the value contained in the USER[.inline-code] environment variable:

$ docker run --rm --env-file .env ubuntu env | grep USERNAME
USERNAME=${USER}