4.2.9.5 ARG ENV Contrast

The ARG-ENV contrast clarifies the distinction between Dockerfile's two variable-setting instructions: ARG defines a value available only during the build, while ENV defines a value that persists into the resulting image's runtime configuration as well.

Lifetime of the Value

An ARG value exists only for the duration of the build; once the image is built, that value is gone unless it was explicitly carried forward into an ENV variable. An ENV value, by contrast, becomes a permanent part of the image's configuration, present in every container started from it.

ARG BUILD_VERSION=1.0
ENV APP_VERSION=$BUILD_VERSION

docker run myapp env

APP_VERSION appears in the running container's environment; BUILD_VERSION does not, since it was never carried forward beyond the build itself.

How Each Is Supplied

ARG values are supplied at build time through --build-arg; ENV values are set directly in the Dockerfile and can be overridden at run time through docker run -e.

docker build --build-arg BUILD_VERSION=2.0 -t myapp .
docker run -e APP_VERSION=custom myapp

Choosing Between Them

Values that should influence how the image is built, but have no meaning once the image exists, belong in ARG. Values that the running application itself needs to read belong in ENV, regardless of whether they also happened to be useful during the build.

ARG INCLUDE_DEBUG_TOOLS=false
ENV LOG_LEVEL=info

The first only matters for deciding what to install during the build; the second is something the application reads directly while running.

A Common Mistake

Using ENV for a value that is only ever needed during the build unnecessarily leaves that value baked into the final image's environment, visible to anyone inspecting a running container, even though it serves no runtime purpose.

ENV TEMP_BUILD_FLAG=true

ARG TEMP_BUILD_FLAG=true

The second is the more appropriate choice if TEMP_BUILD_FLAG is genuinely only relevant during the build process itself.

Why This Contrast Matters

Choosing correctly between ARG and ENV keeps a Dockerfile's intent clear and avoids unnecessarily exposing build-only configuration inside the final, running image.