5.3.3.1 Named Stage Aliases

Named stage aliases are the specific identifiers assigned to build stages through AS, serving as a stable reference point that remains valid even as a Dockerfile's stages are reordered, added, or removed over time.

Choosing Stable, Meaningful Aliases

A good alias describes a stage's purpose rather than some incidental detail that might change, ensuring the alias remains accurate and meaningful even as the stage's specific implementation evolves.

FROM node:20 AS build

FROM node:20 AS node20build

The first alias remains accurate even if the Node.js version later changes; the second would become misleading the moment that happens, despite continuing to technically function.

Reusing an Alias as a New Stage's Base

A named stage can itself serve as the base for another stage, building a chain of stages that each build upon a previous one's established alias.

FROM node:20 AS base
RUN npm install -g pnpm

FROM base AS dependencies
COPY package.json pnpm-lock.yaml ./
RUN pnpm install

FROM dependencies AS build
COPY . .
RUN pnpm run build

Each stage's alias clearly communicates its role, and later stages cleanly build upon earlier ones by referencing their alias directly in a FROM instruction.

Avoiding Alias Collisions

Each stage's alias must be unique within the Dockerfile; reusing the same alias for two different stages causes ambiguity about which one a later reference actually intends.

FROM node:20 AS build
FROM golang:1.22 AS build

This is a mistake, since the duplicate alias makes any later reference to build ambiguous.

Why Named Stage Aliases Matter

Thoughtfully chosen, stable aliases make a multi-stage Dockerfile's structure self-documenting, ensuring that anyone reading the file — or modifying it later — can immediately understand each stage's role and correctly reference it without needing to trace through numeric positions.