Use An .env File In Docker

The short answer

In Docker, environment variables can be defined in a plain text file named [.inline-code].env[.inline-code], 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:

• [.inline-code]VARIABLE[.inline-code] is the name of the environment variable.
• [.inline-code]VALUE[.inline-code] is the value assigned to that variable.

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

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

Where:

• [.inline-code]path[.inline-code] is the path to the [.inline-code].env[.inline-code] file.

• [.inline-code]image[.inline-code] is the name of the base image the container will be launched from.

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

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

[#env-file-syntax] The [.inline-code].env[.inline-code] file syntax [#env-file-syntax]

To be valid, an [.inline-code].env[.inline-code] file must follow a specific set of rules.

[#variable-names] Variable names [#variable-names]

Variable names must:

• Have a maximum length of 64 characters.

• Start with a letter ([.inline-code][a-zA-Z][.inline-code]) or an underscore character ([.inline-code]_[.inline-code]).

Variables can only contain:

• Lowercase and uppercase letters ([.inline-code][a-zA-Z][.inline-code]).

• Numbers ([.inline-code][1-9][.inline-code]).

• Underscores ([.inline-code]_[.inline-code]).

For example:

foobar
DATABASE_URL
_DB_HOST

[#variable-values] Variable values [#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] Comments [#comments]

Any line beginning with [.inline-code]#[.inline-code] will be treated as a comment and will therefore be ignored.

For example:

# This will be ignored
USERNAME=johndoe

[#easily-recall-syntax-with-ai]Easily retrieve this syntax using Warp AI feature[#easily-recall-syntax-with-ai]

If you’re using Warp as your terminal, you can easily retrieve this syntax using the Warp AI feature:

Entering [.inline-code]How to create and load an .env file in Docker?[.inline-code] in the AI question input will prompt a human-readable step by step guide including code snippets.

Using an[.inline-code].env[.inline-code]file per environment

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

For example:

• [.inline-code].env.development[.inline-code]

• [.inline-code].env.staging[.inline-code]

• [.inline-code].env.production[.inline-code]

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

[#load-multiple-env-files] Loading multiple[.inline-code].env[.inline-code]files at once [#load-multiple-env-files]

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

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

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

For example, let's consider the following [.inline-code].env[.inline-code] 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 [.inline-code]DB_HOST[.inline-code], [.inline-code]DB_USER[.inline-code], and [.inline-code]DB_PASSWORD[.inline-code], however, the [.inline-code]DB_HOST[.inline-code] variable will hold the string [.inline-code]"http://localhost:3306"[.inline-code]:

$ 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] Unsupported features [#unsupported-features]

[#multi-line-values] Multi-line values [#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 [.inline-code].env[.inline-code] file:

PRIVATE_KEY="MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6Ppy1tPf9Cnzj4p4WGeKLs1Pt8Qu
KUpRKfFLfRYC9AIKjbJTWit+CqvjWYzvQwECAwEAAQJAIJLixBy2qpFoS4DSmoEm"

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

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

[#inline-comments] Inline comments [#inline-comments]

In Docker, a [.inline-code]#[.inline-code] appearing at the end of a value will be treated as part of the value.

For example, let's consider the following [.inline-code].env[.inline-code] file:

DB_USER="admin" # comment

When launching the following container, the [.inline-code]DB_USER[.inline-code] variable's value will also include the string [.inline-code]# comment[.inline-code]:

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

[#interpolation] Interpolation [#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 [.inline-code].env[.inline-code] file:

USERNAME=${USER}

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

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