How to Set Docker Environment Variables

Introduction

Docker supports environment variables as a practical way of externalizing a containerized app configuration. When included in a Docker image, environment variables become available to app containers created based on the image.

This article shows you how to set Docker environment variables when creating Docker images. It also provides instructions for overriding the default variable values in existing images.

How to set Docker environment variables.

Prerequisites

Types of Docker Environment Variables

A Dockerfile, a script containing instructions for image creation, supports two environment variable types:

  • ARG variables usually store important high-level configuration parameters, such as the version of the OS or a library. They are build-time variables, i.e., their only purpose is to assist in building a Docker image. Containers do not inherit ARG variables from images. However, users can later retrieve ARG values from an image with the docker history command.
  • ENV variables store values such as secrets, API keys, and database URLs. Unlike ARGs, they persist inside the image and the containers created from that template. Users can override ENV values in the command line or provide new values in an ENV file.

How to Set Docker Environment Variables?

Both ARG and ENV variables are defined in the Dockerfile. The following sections describe how to define variables and assign them default and modified values.

Set ARG Values

A Dockerfile can contain just the ARG variable definition or the definition and the variable's default value. When users apply a Dockerfile configuration with the docker build command, they have the option to introduce or modify the value using command-line options.

Follow the steps below to create an ARG variable in Docker:

1. Create a directory for the new Docker image and cd into the path.

mkdir [directory-path] && cd [directory-path]

2. Create a Dockerfile using a text editor. We will be using nano.

nano Dockerfile

3. In the Dockerfile, use the following syntax to define an ARG variable:

ARG [variable-name]

Optionally, assign a default value to the variable by typing:

ARG [variable-name]=[default-value]

For example, to define a variable named TEST1 with the value value1, type:

ARG TEST1=value1

Add the following line to the file for testing purposes.

RUN echo "The ARG variable value is $TEST1"
Defining an ARG variable in a Dockerfile.

Save the file and exit.

4. Execute docker build to create an image. The -t option lets you name the image.

docker build -t [image-name] .

The command output shows Docker going through the Dockerfile and performing the instructions. Step 3 of the procedure executes the test command, which confirms that Docker successfully assigned the value to the variable.

An output showing the successful setting of an ARG variable.

Modify ARG Value with docker build

If you did not provide a value for the ARG variable or want to modify the default value while building the image, use the --build-arg option.

docker build -t [image-name] --build-arg [arg-variable]=[value] .

The example below replaces value1 of the TEST1 variable with new_value.

docker build -t test_image1 --build-arg TEST1=new_value .
Modifying the value of an ARG variable using the command line.

Set ENV Values

Similar to ARG variables, the statement that defines ENV variables in Dockerfile provides the variable's definition and an optional default value. Users can provide values later via the command line or Docker Compose.

Follow the steps below to create an ENV variable:

1. Create a directory for the new Docker image and cd into it.:

mkdir [directory-path] && cd [directory-path]

2. Create a new Dockerfile in a text editor.

nano Dockerfile

3. Define a variable and (optionally) assign it a default value by typing:

ENV [variable-name]=[default-value]

For example, to create the TEST2 ENV variable with the default value of value2, type:

ENV TEST2=value2

Below is an example Dockerfile containing one ARG and one ENV variable.

Defining an ENV variable in a Dockerfile.

To test the procedure, add a line that prints the variable values in the output:

RUN echo "The ARG variable value is $TEST1, the ENV variable value is $TEST2"

Save the file and exit.

4. Build a new Docker image by typing:

docker build -t [image-name] .

The output confirms that the ENV variable was set successfully.

An output showing the successful setting of the ENV variable.

While the ARG variable is unavailable after the image-building process, ENV persists in the containers. To test this property, use docker run to create a container using the image created in this step.

docker run --name [container-name] -d [test-image]:latest

The command outputs the container ID for the new container.

Creating a container using docker run.

Inspect the container by typing:

docker container inspect [container-name-or-id]

The Config section of the output contains a list of environment variables in the container. The example below shows that the ENV variable persisted while the ARG variable no longer exists.

An ENV variable in the configuration section of a Docker container.

Set ENV Value via Command Line

The --build-arg option serves to modify ARG values. To use the option with ENV variables:

1. In a Dockerfile, assign the name of the ARG variable as the value of ENV:

ARG TEST1
ENV TEST2=$TEST1

Add the following command to test this feature:

RUN echo "The ENV variable value is $TEST2"
Setting the value of an ENV variable to an ARG variable.

2. Build the image. Use the --build-arg option to pass a value to ARG:

docker build --build-arg [arg-variable]=[value] .

The output shows that Docker processed the ARG value and assigned it to ENV.

An output confirming the successful modification of the ENV variable from the command line.

How to Override Docker Environment Variables

Users override ENV variable defaults defined in the Dockerfile in multiple ways. In order of precedence, the application considers the values set by:

  • The containerized application itself.
  • The -e command-line argument of the docker run command.
  • The .env file provided through the docker run --env-file option.
  • The Dockerfile.

Overriding Single ENV Variable via Command Line

Use the -e option with docker run to override a single defined ENV variable when creating a container.

docker run --name [container-name] -e "[variable-name]=[new-value]" [image-name]

The example below changes the value of TEST2 to runtime_value while creating the test_container1 from test_image3:

docker run --name test_container1 -e "TEST2=runtime_value" test_image3

With Docker Compose, place the value you wish to override in the environment section of the file:

version: '[version-number]'

services:
  [service-name]:
    image: [image-name]
      environment:
        - env_var_name=[new-value]

The new value appears when inspecting test_container1:

docker container inspect test_container1
An ENV variable with the assigned runtime value in the config section of a Docker container.

Overriding Multiple ENV Variables with ENV File

Provide a set of variable values on runtime by creating an ENV file that contains the relevant key-value pairs.

1. Create the file with a text editor:

nano [env-filename]

2. Populate the file with key-value pairs:

[variable1-name]=[value1]
[variable2-name]=[value2]
[variable3-name]=[value3]
...

Save the file and exit.

3. Pass the values from the file with the --env-file option.

docker run --name [container-name] --env-file [path-to-env-file] [image-name]

If you are using Docker Compose, use the env_file field to reference the ENV file:

version: '[version-number]'

services:
  [service-name]:
    image: [image-name]
    env_file: [env-file-path]

Note: Containers are an essential part of every Kubernetes deployment. To improve container management efficiency and quickly deploy a production-ready Kubernetes environment, use Rancher on Bare Metal Cloud.

Conclusion

After reading this tutorial, you should know how to define and set ARG and ENV environmental variables in a Dockerfile and how to override their values using Docker CLI and Docker Compose.

Next, learn how to mount NFS Docker volumes.

Was this article helpful?
YesNo
Marko Aleksic
Marko Aleksić is a Technical Writer at phoenixNAP. His innate curiosity regarding all things IT, combined with over a decade long background in writing, teaching and working in IT-related fields, led him to technical writing, where he has an opportunity to employ his skills and make technology less daunting to everyone.
Next you should read
Docker CMD vs. Entrypoint Commands
February 18, 2020

In this article, we explain the differences between Docker ENTRYPOINT and CMD and when to use which Docker instruction.
Read more
How to Resolve the “cannot connect to the Docker daemon” Error
December 10, 2020

This tutorial discusses possible causes of the “cannot connect to the Docker daemon” error...
Read more
How to Optimize Docker Performance
November 25, 2021

Docker containers are designed to run anywhere - in an in-house data center, the cloud, or a hybrid and multi-cloud environment...
Read more
Docker Image vs Container: The Major Differences
November 24, 2022

Although Docker is relatively simple to master, there are some Docker-specific terms that new users may find confusing. Dockerfiles, images, containers, volumes...
Read more