Sometimes when building Docker images, you may need to use variable data to customize the build. The ARG instruction is the tool to handle that situation. To use it, you add ARG instructions to your Dockerfile, and then when you execute the build command, you pass in the variable data with a --build-arg parameter. The --build-arg parameter uses the now familiar key-value pair format:

# The ARG instruction syntax
ARG <varname>[=<default value>]

# The build-arg parameter syntax
docker image build --build-arg <varname>[=<value>] ...

You can use multiple ARG instructions in your Dockerfile with corresponding --build-arg parameters on the docker image build commands. You have to include an ARG instruction for every use of the --build-arg parameter. Without the ARG instruction, the --build-arg parameter will not be set during the build, and you will get a warning message. If you do not provide a --build-arg parameter or you do not provide the value part of the key-value pair for a --build-arg parameter for an existing ARG instruction, and that ARG instruction includes a default value, then the variable will be assigned the default value.

Be aware that during the image build, even though --build-arg is included as a parameter of the docker image build command, the corresponding variable does not get set until the ARG instruction is reached in the Dockerfile. Said another way, the value of the key-value pair of a --build-arg parameter will never be set until after its corresponding ARG line in the Dockerfile.

The parameters defined in ARG instructions do not persist into containers run from the created image, however, ARG instructions create new zero-byte-sized layers in the resulting images. Here is an educational example of using the ARG instruction:

# ARG instruction Dockerfile for Docker Quick Start
FROM alpine
LABEL maintainer="Earl Waud <[email protected]>"

ENV key1="ENV is stronger than an ARG"
RUN echo ${key1}
ARG key1="not going to matter"
RUN echo ${key1}

RUN echo ${key2}
ARG key2="defaultValue"
RUN echo ${key2}
ENV key2="ENV value takes over"
RUN echo ${key2}
CMD ["sh"]

Create a Dockerfile with the contents shown in the preceding code block and run the following build command to see how the scope of the ENV and ARG instructions play out:

# Build the image and look at the output from the echo commands
 docker image build --rm 
 --build-arg key1="buildTimeValue" 
 --build-arg key2="good till env instruction" 
 --tag arg-demo:2.0 .

You will see by the first echo ${key1} that even though there is a --build-arg parameter for key1, it will not be stored as key1 because there is an ENV instruction that has the same key name. This still holds true for the second echo ${key1}, which is after the ARG key1 instruction. The ENV variable values will always be the winner when there are both ARG and EVN instructions with the same key name.

Then, you will see that the first echo ${key2} is empty even though there is a --build-arg parameter for it. It is empty because we have not reached the ARG key2 instruction yet. The second echo ${key2} will contain the value from the corresponding --build-arg parameter even though there is a default value provided in the ARG key2 instruction. The final echo ${key2} will show the value provided in the ENV key2 instruction in spite of there being both a default value in the ARG and a value passed in via the --build-arg parameter. Again, this is because ENV always trumps ARG.