4.2.9.3 ARG Build Parameters

A focused guide to ARG Build Parameters, connecting core concepts with practical Docker and container operations.

ARG build parameters refers to the overall practice of using multiple ARG instructions together to make a Dockerfile configurable across several independent dimensions — version, target platform, feature flags — supplied collectively at build time to produce a specific variant of an otherwise shared image definition.

Declaring Several Related Parameters

A Dockerfile can declare multiple ARG instructions, each controlling a different aspect of the build, combined to produce many possible build variants from a single file.

ARG NODE_VERSION=20
ARG BUILD_ENV=production
ARG INCLUDE_DEBUG_TOOLS=false

FROM node:$NODE_VERSION-alpine
RUN if [ "$INCLUDE_DEBUG_TOOLS" = "true" ]; then apk add --no-cache vim; fi
ENV NODE_ENV=$BUILD_ENV

Supplying Multiple Parameters at Build Time

Each declared parameter can be independently supplied, allowing precise control over exactly which variant of the image a given build invocation produces.

docker build \
  --build-arg NODE_VERSION=18 \
  --build-arg BUILD_ENV=development \
  --build-arg INCLUDE_DEBUG_TOOLS=true \
  -t myapp:dev .

Documenting Available Parameters

Because the available build parameters and their defaults are visible directly in the Dockerfile, anyone needing to build a custom variant can discover what is configurable simply by reading the file, without needing separate documentation.

grep "^ARG" Dockerfile

This quickly surfaces every configurable build parameter a given Dockerfile supports.

Combining Build Parameters With CI Pipelines

Build pipelines commonly supply these parameters automatically based on the specific build being performed, such as setting BUILD_ENV based on which branch or pipeline stage triggered the build.

docker build --build-arg BUILD_ENV=$CI_ENVIRONMENT_NAME -t myapp:$CI_COMMIT_SHA .

Why ARG Build Parameters Matter

A well-parameterized Dockerfile reduces duplication across what would otherwise be several nearly identical files, while keeping each build variant's specific configuration explicit, discoverable, and reproducible from a single shared definition.