4.2.1.2 FROM Stage Alias

A FROM stage alias is the optional name assigned to a build stage using the AS keyword, which allows later parts of a multi-stage Dockerfile to reference that specific stage explicitly, rather than only ever referencing the immediately preceding stage by position.

Naming a Stage

Adding AS <name> after a FROM instruction gives that build stage a name that can be referenced elsewhere in the Dockerfile.

FROM golang:1.22 AS build
WORKDIR /src
COPY . .
RUN go build -o app .

This stage is now referenceable by the name build, rather than only by its position in the file.

Referencing a Named Stage

A later stage can copy files from any previously named stage using COPY --from=<name>, regardless of how many other stages appear in between.

FROM debian:bookworm-slim
COPY --from=build /src/app /usr/local/bin/app
CMD ["app"]

Why Naming Stages Improves Readability

In a Dockerfile with several build stages, referring to each by a descriptive name rather than a numeric index makes the file significantly easier to read and maintain, since the relationship between stages is clear from the names themselves rather than requiring the reader to count stage positions.

FROM node:20 AS frontend-build
FROM golang:1.22 AS backend-build
FROM debian:bookworm-slim AS final

A reader can immediately understand the purpose of each stage from its name, without needing to trace through what each one actually does first.

Referencing an Earlier Stage as a New Stage's Base

A named stage can also be used directly as the base for a later stage, not just as a source for COPY --from, allowing one stage to build directly on top of another.

FROM node:20 AS base
RUN npm install -g some-global-tool

FROM base AS build
WORKDIR /app
COPY . .
RUN npm run build

Why FROM Stage Aliases Matter

Named stage aliases are essential for managing complexity in multi-stage builds with more than two stages, turning what would otherwise be an easily confused sequence of positional references into a clear, self-documenting structure.