Multi-stage builds: a fat builder, a thin runtime, and how COPY --from collapses 1.2 GB into 28 MB

Two jobs, two stages

Ask yourself: does the running container actually need the compiler that built it? Almost never — yet single-stage builds ship both environments in the same layers. A single-stage build conflates two different filesystems: the one you need to build an artifact (compilers, package managers, headers, source, module caches) and the one you need to run it (the binary plus its actual runtime dependencies). Multi-stage separates them. You write several FROM stages in one Dockerfile; the last one is the image you ship, and earlier stages exist only to produce inputs the final stage copies in.

# syntax=docker/dockerfile:1
FROM golang:1.23 AS build           # ~840 MB: compiler, git, module cache
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app ./cmd/server

FROM gcr.io/distroless/static:nonroot AS runtime   # ~2 MB base
COPY --from=build /app /app          # copy ONLY the binary
USER nonroot
ENTRYPOINT ["/app"]

COPY --from=build /app /app is the hinge. It reaches into the build stage’s final filesystem and copies just /app into the runtime stage. The compiler, the 400 MB module cache, the source tree, git — none of it crosses the boundary. The shipped image is the distroless base plus one 18 MB binary layer: 28 MB total, against the 1.2 GB single-stage image. Same binary, 40× smaller, and the entire build toolchain — every CVE-bearing dev package — is simply absent from the layers a customer pulls.

Only the target stage (and its deps) gets built

A second property people miss: docker build builds the final target stage and only the stages it transitively depends on. Unreferenced stages are pruned from the LLB graph and never execute. So you can keep a test stage and a lint stage in the same Dockerfile, and a plain docker build (targeting the runtime stage) skips them entirely unless something COPY --froms their output. You can also build a specific stage with --target build to get a debug image with the full toolchain, or --target test in CI to run tests inside the graph. One Dockerfile, several outputs, and the production build pays for none of the stages it does not reference.

The COPY-from-stage cache trap

Multi-stage interacts with caching in a way that bites people. The runtime stage’s COPY --from=build /app vertex is keyed on the digest of /app as produced by the build stage. So if the build stage’s compile is a cache hit and produces the identical binary, the COPY --from hits cache too and the runtime layer is reused. But if your build is non-deterministic — embedding a timestamp, a random build ID, or a Go build that varies — /app’s digest changes every build, the COPY --from always misses, and you push a new runtime layer to the registry every time even when nothing meaningful changed. The same content addressing that makes the cache work makes non-reproducible builds expensive: a reproducible compile lets the final layer be a stable cache hit, which is exactly what the next lesson on reproducible builds is about. The discipline: order the build stage like any other (manifests before source), and keep the artifact deterministic so the cross-stage copy can cache.