4.2.9.2 ARG Default Values
A focused guide to ARG Default Values, connecting core concepts with practical Docker and container operations.
ARG default values are the fallback values an ARG instruction declares for its variable, used automatically whenever a build does not explicitly supply a value through --build-arg, ensuring the Dockerfile still builds successfully without requiring every invocation to specify every variable.
Declaring a Default
A default is specified directly as part of the ARG instruction, used unless explicitly overridden at build time.
ARG VERSION=1.0
RUN echo "Building version $VERSION"
docker build -t myapp .
Without any --build-arg flag, this build uses 1.0 as the value of VERSION, exactly as declared.
Declaring ARG Without a Default
An ARG can also be declared without a default value, in which case it is empty unless explicitly supplied, which can be useful when a value genuinely should be required rather than silently defaulting to something potentially incorrect.
ARG API_KEY
RUN echo "Using API key: $API_KEY"
docker build --build-arg API_KEY=abc123 -t myapp .
Without supplying --build-arg API_KEY=..., this would proceed with an empty value, which might or might not be an acceptable outcome depending on what that value is used for.
Choosing Sensible Defaults
A thoughtfully chosen default allows a Dockerfile to be built successfully with the simplest possible invocation, while still supporting customization when genuinely needed.
ARG NODE_VERSION=20
Choosing the currently preferred or most broadly compatible version as the default means most builds never need to specify this variable explicitly at all.
Verifying Which Default Was Actually Used
Because a build's actual behavior depends on whether a default or an explicitly supplied value was used, it can be useful to have the build output or logs confirm which value was actually applied.
RUN echo "Building with NODE_VERSION=$NODE_VERSION"
Why ARG Default Values Matter
Sensible default values keep a parameterized Dockerfile convenient to use in the common case, while the underlying flexibility remains available for the less common cases that genuinely need a different value.