Multi-stage Docker builds that cut image size by 80%

Split build tooling from the runtime so your final image ships only the binary and its deps — smaller, faster, safer.

The image that runs in production only needs the compiled program, and yet the single-stage Dockerfile most projects start with ships the compiler, the module cache, the source tree, the apt lists and, if anyone ever passed a token through ARG, that token's layer too. A multi-stage build separates building from shipping: the first stage has every tool and every secret, the last stage receives the one artifact you copy into it, and nothing else crosses the boundary.

What crosses the stage boundary, exactly

Only the paths named in COPY --from=<stage> end up in the final image. Environment variables, ARG values, files written anywhere else, and every layer of the build stage stay in the build cache and are not part of what docker push sends. That is also the trap: COPY --from=build / / copies the entire build filesystem and defeats the point. On the engine used for this article it did not even get that far: the whole-root copy onto a distroless base failed with cannot replace to directory …/var/lock with file, because the two filesystems disagree about what /var/lock is. The version of the mistake that does build is copying whole directories, and it costs what you would expect: COPY --from=build /src /src plus COPY --from=build /usr/local/go /usr/local/go produced a 246.6 MB image with main.go and the go binary in its layers. Copy the binary, or the dist/ directory, by explicit path.

# syntax=docker/dockerfile:1
# --- build stage: toolchain, module cache, secrets allowed ---
FROM golang:1.27 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
COPY . .
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=secret,id=netrc,target=/root/.netrc \
    CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/app ./cmd/app
 
# --- test stage: runs in CI, never becomes the shipped image ---
FROM build AS test
RUN go vet ./... && go test ./...
 
# --- runtime stage: the binary, CA certificates, tzdata, nothing else ---
FROM gcr.io/distroless/static-debian13:nonroot
COPY --from=build /out/app /app
USER nonroot:nonroot
ENTRYPOINT ["/app"]

Three details in that file do real work. RUN --mount=type=secret exposes a credential to one build step without writing it into any layer, which ARG and ENV cannot promise. The test stage inherits from build and is selected with docker build --target test in CI, so tests run against the exact compiled artifact while the default build (no --target) produces the runtime image without test binaries. And CGO_ENABLED=0 is what makes the static distroless variant usable: a dynamically linked binary needs base-debian13 (glibc and libssl) or cc-debian13 instead.

In CI the two invocations share a cache: docker build --target test --secret id=netrc,src=$HOME/.netrc . compiles and tests, then docker build -t app:$SHA . reuses every layer of the build stage from the first command and only adds the runtime stage. The secret is passed at build time from the runner's file and is readable only inside the one RUN that mounts it; docker history app:$SHA afterwards shows no layer that could contain it, which is the check worth automating. A stronger version of that check is to search the layers themselves rather than their descriptions, and it is the one the fixture runs: docker save the image, extract every layer tar, and grep the raw content for the token.

Which stages actually run depends on the builder. BuildKit builds only the stages the selected target depends on, so a Dockerfile can carry a test stage, a lint stage and a docs stage without any of them costing a production build a second; the legacy builder processed every stage up to the target regardless. The fixture carries a never stage whose only instruction is exit 1: the default build succeeded and its progress log names only the build and runtime stages, --target test ran go vet and go test, and --target never failed the build as it should. That difference is also why a stage nobody references makes a poor hiding place: one builder skips it, the other builds and caches it where docker history can read it. A stage that must never ship is kept out of the runtime stage's COPY --from list, which is the only boundary that holds in both.

When a build change ships the wrong thing: recovery in order of preference

Choosing the runtime stage

Runtime bases for a multi-stage build

For interpreted stacks the artifact is a directory rather than a binary. A node:24 build stage runs npm ci && npm run build; the runtime stage copies dist/ and a production-only node_modules produced by npm ci --omit=dev in a separate step, not the development tree from the build stage. Java is the same shape with a JDK stage feeding a java21-debian13 runtime.

The size drop is the visible result; the security result is that the tools an attacker relies on after code execution (a shell, curl, a package manager) are not present. What distroless removes and what it leaves is the subject of running containers without a shell, and the layer ordering that keeps these builds fast is in Dockerfile layer caching.

Related posts

Quick reference