5.3.1.4 Builder Artifact Output

Builder artifact output is the specific, final output a builder stage produces — a compiled binary, a bundled set of static files, a packaged archive — which is the only thing a later stage actually needs to copy forward, leaving everything else the builder stage used or produced behind.

Identifying What the Final Stage Actually Needs

A builder stage often produces many intermediate files, cached dependencies, and temporary artifacts; identifying precisely which output is the genuinely necessary final result is what determines what a subsequent COPY --from instruction should actually copy.

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

FROM scratch
COPY --from=builder /out/app /app

Only the compiled binary at /out/app is copied forward; the entire Go toolchain, source code, and any other intermediate build state remains behind in the discarded builder stage.

Structuring Build Output Into a Clear, Dedicated Location

Directing a build's output to a specific, clearly named directory (rather than scattering it throughout the builder stage's filesystem) makes the subsequent COPY --from instruction simpler and less likely to inadvertently include unintended files.

RUN npm run build -- --output-dir=/build-output

COPY --from=builder /build-output /usr/share/nginx/html

Verifying Only the Intended Artifact Crosses Over

Confirming the final image contains exactly the expected artifact, and nothing more, validates that the builder stage's output was correctly identified and copied.

docker run --rm myapp:1.0 ls -la /

Why Builder Artifact Output Matters

A clear, deliberate understanding of exactly what a builder stage's true final output is — and structuring that stage to produce it in an easily identifiable location — is what makes the entire multi-stage pattern work cleanly, ensuring the final image contains only what it actually needs to run.