Docker Environment Variables Example

When we create a Docker container, sometimes, we have the need of passing “arguments” to it, typically, port numbers for services, or some paths.

For this, we configure the environment variables of the container, and that’s what this example is going to show.

For this example, Linux Mint 18 and Docker version 1.12.1 have been used.

You may skip Docker installation and jump directly to the beginning of the example below.

1. Installation

Note: Docker requires a 64-bit system with a kernel version equal or higher to 3.10.

We can install Docker simply via apt-get, without the need of adding any repository, just installing the package:

sudo apt-get update
sudo apt-get install

For more details, you can follow the Install Docker on Ubuntu Tutorial.

2. What are environment variables?

When we talk about environment variables in Docker context, we are talking about the variables that we pass to a container, that will be set in its environment. Pretty easy, as you can see.

Let’s see a practical case, executing the env command inside a container. In my case, is a container named busybox1, based on a Busybox image, that we have created just running:

docker run -i -t -d --name=busybox1 busybox

(The -i, -t and -d options are for keeping the container alive, detached).

Now, we can execute the env command:

docker exec busybox1 env

Receiving the following output:


Showing the list of the environment variables set in our container.

Note that the concept is exactly the same than in Linux, but applied in Docker context. Now we will see how to deal with environment variables in Docker containers.

3. Setting environment variables

Is essential to understand that the environment variables are set in container instantiation, that is, when we execute the run command.

For this, we have to use the -e (--env) option. The format is the following:

docker run -e <variable1>='<value1>' [-e <variableN>='<valueN>'] <image>

There are a couple of things that we have to take into account:

  • We have to pass the -e for each variable.
  • The quotes for the value are only required for values including whitespaces, but it’s always good to follow the same convention, adding them always.

Let’s see an example, creating the container and executing the env command (inside the container; not a Docker command), and seeing the output:

docker run -e variable1='value1' -e variable2='value2' busybox env

The shown output is:


3.1. Reading environment variables from a file

Docker gives the chance of reading the environment variables from a file, which is especially useful when we have a large list of variables and we want to reuse them.

The format this file has to follow is very simple, it’s just about setting a var=val in different lines, for example:



This file does not have to have any specific naming; we can set the name and extension we want.

Also, note that we shouldn’t use quotes if we use a environment variable list file: if we use them, the quotes will be part of the value itself.

For specifying this file when instantiating the image, we have to use the env-file option:

docker run --env-file=<path/to/file> <image>

For example:

docker run --env-file=./env.list busybox env

If we execute the command shown above, we will see that the printed environment variable list is the same as in previous occasions, but now being defined in a file.

We can also combine the usage of the file, and the specification of the variables inline:

docker run --env-file=./env.list -e variable3=value3 busybox env



Of course, we have to be cautious with the redefinitions: if a variable is defined in both file and inline, the one defined inline will have precedence. This means that, for the previous env.list, if we also define the following inline variable:

docker run --env-file=./env.list -e variable2=value3 busybox env

The value set in the container for variable2 will be value3, instead of value2.

4. Environment variables in Dockerfiles

Of course, we can set environmental variables in our Dockerfiles. For this, we have to use the ENV instruction.

There are several ways for using this instruction:

# Without equality sign, specifying the 'ENV' instruction in each line
ENV variable1 value1
ENV variable2 value2

# With the equality sign, without the need of specifying 'ENV' for every assignment, but using '\'
ENV variable1=value1\

As for inline variables, we have to use quotes for values containing whitespaces.

So a simple Dockerfile for doing what we have done in the previous sections could be:


FROM busybox

ENV variable1=value1\

Then, we build the image from this Dockerfile:

docker build --tag=mybusybox . # The path to my Dockerfile

And run it, showing the environment variables:

docker run mybusybox env

And we will see the expected output:


5. Summary

In this tutorial, we have seen how to set environment variables of containers at instantiation time, as a method of passing arguments to them. We have started with the most basic solution, that consists on passing the arguments inline one by one; and then how to define them in a file, which can be more comfortable for some situations; and, also, for our own Dockerfiles.

Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments
Back to top button