15182

15182.md

ARG

ARG [--default=<value>] [--description=<value>] <arg name>

The ARG instruction defines a variable that users can pass at build-time to the builder with the docker build command using the --build-arg <varname>=<value> flag. If a user specifies a --build-arg but it is not used by the builder, the build outputs a warning.

One or more build-args %v were not consumed, failing build.

The Dockerfile developer can define a single variable by specifying ARG once or many variables by specifying ARG more than once. For example, a valid Dockerfile:

FROM busybox
ARG user
ARG buildno
...

A Dockerfile developer may optionally specify a default value and description for an ARG instruction:

FROM busybox
ARG user
ARG buildno --default="XXX"
...

If an ARG value has a default and if there is no value passed at build-time, the builder uses the default. The default value and the description are persisted in the image metadata. Persistence makes these optional flags useful as documentation. If an ARG does not contain either of these flags, the ARG is not persisted.

An ARG variable definition comes into effect from the line on which it is defined in the Dockerfile not from the argument's use on the command-line or elsewhere. For example, consider this Dockerfile:

1 FROM busybox
2 USER ${user:-some_user}
3 ARG user
4 USER $user
...

A user builds this file by calling:

$ docker build --build-arg user=what_user Dockerfile

The USER at line 2 evaluates to some_user as the ARG user is defined on the subsquent line 3 line. The USER at line 4 evaluates to what_user as user is defined and what_user was passed on the command line. Prior to its definition by an ARG instruction, any use of a variable results in an empty string.

Note: It is not recommended to use build-time variables for passing secrets like github keys, user credentials etc.

You can use an ARG or an ENV instruction to specify variables that are available to the RUN instruction. Environment variables defined using the ENV primitive of Dockerfile always override an ARG instruction of the same name. Consider this Dockerfile with an ENV and ARG instruction.

1 FROM ubuntu
2 ARG CONT_IMG_VER
3 ENV CONT_IMG_VER v1.0.0

Then, assume this image is built with this command:

$ docker build --build-arg CONT_IMG_VER=v2.0.1 Dockerfile

In this case, the RUN primitive uses v1.0.0 instead of the ARG setting passed by the user:v2.0.1 This behavior is similar to a shell script where a locally scoped variable overrides the variables passed as arguments or inherited from environment, from it's point of definition.

Using the example above but a different ENV specification you can create more useful interactions between ARG and ENV instructions:

1 FROM ubuntu
2 ARG CONT_IMG_VER
3 ENV CONT_IMG_VER ${CONT_IMG_VER:-v1.0.0}

The command line passes the --build-arg and sets the v2.0.1 value. And the ARG CONT_IMG_VER is defined on line 1 of the Dockerfile. On line 3, the ENV instruction of the same name resolves to to v2.0.1 as the build-time variable was passed from command line and expanded here.

The variable expansion technique in this example allows you to pass arguments from command-line and persist them in the final image by leveraging the ENV primitive. Variable expansion is only supported for the Dockerfile primitives described here.

Unlike an ARG instructions, ENV values are always persisted in the built image. If docker build were run without setting the --build-arg variable, then CONT_IMG_VER is still persisted in the image but its value would be v1.0.0.

Finally, Docker has set of predefined ARG variables that you can use.

• HTTP_PROXY
• HTTPS_PROXY
• http_proxy
• https_proxy
• FTP_PROXY
• NO_PROXY

To use these, simply pass them on the command line using the --build-arg <varname>=<value> flag. You can also define defaults for these in a Dockerfile.