4.2.9 ARG

ARG is the Dockerfile instruction that defines a build-time variable, available only during the build process itself, distinct from ENV in that its value does not automatically persist into the final image's runtime configuration.

Basic Usage

ARG declares a variable that can be supplied a value at build time, with an optional default if none is explicitly provided.

ARG VERSION=1.0
RUN echo "Building version $VERSION"

docker build --build-arg VERSION=2.0 -t myapp .

If --build-arg is not supplied, the declared default value is used instead.

ARG Values Do Not Persist Into the Image by Default

Unlike ENV, a value set through ARG is only available during the build and does not automatically become part of the resulting image's environment, unless explicitly assigned to an ENV variable.

ARG BUILD_VERSION=1.0
ENV APP_VERSION=$BUILD_VERSION

This explicitly carries the build-time value forward into the image's persistent ENV configuration; without this step, BUILD_VERSION would simply cease to be accessible once the build finished.

Scoping ARG to Specific Build Stages

In a multi-stage build, an ARG declared before the first FROM is available to be referenced in FROM instructions themselves, but must be redeclared within a stage to be available to instructions inside that stage.

ARG BASE_VERSION=3.12
FROM python:$BASE_VERSION-slim
ARG BASE_VERSION
RUN echo "Built on Python $BASE_VERSION"

Why ARG Matters for Build Flexibility

ARG allows a single Dockerfile to support build-time customization — different versions, different feature flags affecting the build — without needing separate Dockerfiles for each variation, while still keeping build-only configuration cleanly separated from the image's actual runtime environment.

docker build --build-arg VERSION=3.0 -t myapp:3.0 .