Multi-Stage Builds: Small, Fast, Secure Images

Introduction

To build many applications you need compilers, package managers and build tools — but to run them, you need none of that. Multi-stage builds let one Dockerfile use a big image for building and a tiny image for running, so your final image contains only what the application needs.

The Problem: Build Tools in Your Image

Priya has written a small web service in Go. Go compiles a program into a single executable file, which makes it a perfect example. Her project has three files:

tree

package main

import (
	"fmt"
	"log"
	"net/http"
	"os"
)

func main() {
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		host, _ := os.Hostname()
		fmt.Fprintf(w, "Hello from a tiny Go container (%s)\n", host)
	})
	log.Println("listening on :8080")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

Her first Dockerfile is a straightforward single stage: start from the official Go image, copy the code, compile it, run it:

FROM golang:1.27-alpine
WORKDIR /src
COPY . .
RUN go build -o /hello .
EXPOSE 8080
CMD ["/hello"]

docker build -t hello-go:single .

It works, but the image includes the entire Go compiler and standard library source — over 70 MB just for one of its layers — none of which the finished program needs.

Writing a Multi-Stage Dockerfile

A multi-stage Dockerfile has several FROM lines. Each starts a new stage, and only the last stage becomes the final image. Earlier stages can be named with AS, and later stages copy files out of them with COPY --from:

# Stage 1: build the program with the full Go toolchain
FROM golang:1.27-alpine AS build
WORKDIR /src
COPY go.mod ./
COPY *.go ./
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /hello .

# Stage 2: copy only the finished program into an empty image
FROM scratch
COPY --from=build /hello /hello
EXPOSE 8080
ENTRYPOINT ["/hello"]

docker build -t hello-go:multi .

BuildKit labels each step with its stage: [build 1/5] to [build 5/5] for the build stage, then [stage-1 1/1] for the final, unnamed stage. Note that WORKDIR /src was CACHED — it was identical to the single-stage build.

Comparing the Results

docker images hello-go

From 508 MB to 8.38 MB on disk — about 60 times smaller, and only 2.52 MB to download. It still works exactly the same:

docker run -d --name hello -p 8080:8080 hello-go:multi > /dev/null
sleep 1
curl -s http://localhost:8080/
docker logs hello

Images Without a Shell

The scratch image really is empty — there is not even a shell, so you cannot exec into the container:

docker exec -it hello sh

That is good for security but makes debugging harder. If you need a few basic tools, use a small base such as alpine for the final stage instead of scratch. Another popular choice is Google’s “distroless” images, which contain language runtimes and CA certificates but no shell or package manager. Note also that scratch has no CA certificates: a Go program that calls HTTPS APIs needs them copied in from the build stage (COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/).

Building One Stage: --target

--target stops the build at a named stage. That is handy for debugging the build itself, or for running tests in the build environment:

docker build -q --target build -t hello-go:build-stage . > /dev/null
docker run --rm hello-go:build-stage go version

Multi-Stage for Other Languages

A front-end example — the Node image builds the site, and Nginx serves the result:

FROM node:24-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html

Common Mistakes

Frequently Asked Questions

Key Takeaways

Summary

You can now build images that are small, fast and safe. Next you will learn to diagnose containers that crash, refuse to start or behave strangely.