4.2.8.4 ENV Variable Expansion

ENV variable expansion is the ability to reference a previously set environment variable's value within a later Dockerfile instruction, letting one ENV (or other instruction) build on a value established earlier rather than repeating it.

Referencing an Earlier ENV Value

A later instruction can reference an environment variable set earlier in the same Dockerfile, with Docker substituting its current value before the instruction executes.

ENV APP_HOME=/app
ENV APP_CONFIG=$APP_HOME/config.yaml
WORKDIR $APP_HOME

Here, APP_CONFIG is built directly from the previously set APP_HOME, and WORKDIR itself also references the same variable rather than repeating the literal path.

Expansion Within RUN Instructions

Variables set with ENV are also available for expansion within RUN instructions, since they exist in the environment of the temporary container each RUN instruction executes in.

ENV APP_HOME=/app
RUN mkdir -p $APP_HOME/data

Expansion Syntax Variations

Both $VARIABLE and ${VARIABLE} syntax are supported for expansion, with the braced form being necessary when a variable name needs to be immediately followed by additional characters that could otherwise be misread as part of the variable name.

ENV APP_VERSION=1
ENV APP_VERSION_TAG=v${APP_VERSION}-release

Without the braces here, it would be ambiguous whether _release was intended to be part of the variable name being referenced.

Combining Build Arguments With ENV Expansion

ARG values, available only during the build, are often expanded into ENV values that should persist into the final image, combining build-time configurability with runtime availability.

ARG VERSION=1.0
ENV APP_VERSION=$VERSION

Why ENV Variable Expansion Matters

Variable expansion reduces repetition and the risk of inconsistency that comes from manually repeating the same literal value across multiple instructions, making a Dockerfile easier to maintain, especially when a single underlying value (like a base path or version number) needs to be referenced in several different places.