Pass Docker Environment Variables During the Image Build

November 04, 2017

Docker ENV and ARG are pretty similar, but not quite the same. ARG can be set during the image build, directly in the Dockerfile and used in commands. However, it’s not available anymore as soon as the image is actually built. Neither the ENTRYPOINT command, nor anything else in the future containers can access those values.

ENV variables are different - they stick around during the build and any containers which are run from the image. You can set default values directly in the Dockerfile, but can’t specify dynamic ENV values during the build, or can you?

Setting ENV Values

During the build, you can only set the values of ARG variables, using the --build-arg flag. There’s no such thing to set the default values of ENV, variables, but you have two choices: Hard coding a value, or using ARG to pass a value to an ENV variable.

The first is pretty straight-forward:

ENV env_var_name=some_value

But that’s dull and anything but dynamic. You don’t want to edit your Dockerfile every time the value is not up-to-date anymore. You can use the values of ARG variables to specify a default ENV value this way in your Dockerfile:

ARG var_name
ENV env_var_name=$var_name

That value will be available to future containers, but can be overridden while running a container.

Using Host Environment Variable Values to Set ARGs

What if you want to set the ARG value based on a variable in your current environment? You simply pass the value using bash command substitution.

$ docker build --build-arg var_name=${VARIABLE_NAME} (...)

The dollar-notation will be substituted with the value of the current environment variable. Alternatively, you can pass the value from the environment automatically, if your variable in the Dockerfile is named the same as the env var in question. Just don’t provide a value:

$ docker build --build-arg var_name (...)


Keep in mind, that default ARG and ENV values are not suitable to keep secrets which you don’t want to stick around. Default and dynamic ARG values can be seen after the image is built using the docker history command. Default ENV values can be discovered in many ways, among them using the inspect command. You can circumvent this, using multi-stage builds.

Next Steps

In the article above, you’ve seen a way to set Docker environment variables during the image build, and how to pass the values of host env vars to the Dockerfile without specifying them every single time. There’s a lot more to really understand and master using ARG and ENV with Docker.

If you want to get a good overview of build-time arguments, environment variables, env_files and docker-compose templating with .env files - head over to this in-depth guide and give it a read.

I’m sure you’ll get quite a bit of value out of it, and will be able to use the knowledge to save yourself lots of bugs in the future.

Join the Mailing List

Subscribe to get weekly updates and my latest articles by email.

    (About the content, privacy, analytics and revocation).

    We won't send you spam. Unsubscribe at any time.

    Powered By ConvertKit