Docker Multi-Stage Builds for Image Optimization

·12 min read·Cloud and DevOpsintermediate

Cutting image size and attack surface without sacrificing developer experience

Close-up of a Dockerfile with multi-stage FROM statements on a developer workstation screen

I used to ship Docker images that were north of 1.2 GB. They contained compilers, headers, test suites, and a tangle of cached dependencies we “might need later.” Deployments were slow, registry bills crept up, and security scans lit up like Christmas trees. The switch to Docker multi-stage builds wasn’t glamorous, but it cut our Node.js and Go images by 70–80% and made pipelines noticeably faster. This post is the guide I wish I’d had when I started: practical patterns, real tradeoffs, and examples you can adapt to your stack.

If you’re building containerized applications today, you probably care about four things: image size, security posture, reproducibility, and developer ergonomics. Multi-stage builds address all of them by letting you separate build-time concerns from runtime needs. The concept is simple, but the impact is significant—especially in cloud environments where registry egress, cold start times, and base image vulnerabilities directly affect cost and reliability. In the next sections, we’ll explore where multi-stage fits in modern workflows, how to structure it in practice, where it shines, and where it might not be the right tool.

Context: Where multi-stage builds fit in today’s cloud and DevOps workflows

Containers have become the default packaging format for modern apps, but base images have grown heavier over time. Official language images often bundle build toolchains for convenience, which increases size and attack surface. Teams working in microservice architectures, Kubernetes clusters, and serverless platforms feel this pain acutely: small images mean faster scaling, lower registry costs, and quicker rollbacks. Meanwhile, CI pipelines benefit from layered caching and smaller artifacts, cutting runtimes and minimizing resource contention.

Developers and platform engineers use multi-stage builds to:

  • Keep runtime images minimal by compiling artifacts in a “builder” stage and copying only the output.
  • Reduce dependencies like compilers, -dev packages, and test suites that aren’t needed at runtime.
  • Harden images by excluding shell and package managers from the final stage where possible.

Compared to alternatives—like manually crafting a slim base image or relying on post-build trimming tools—multi-stage builds are explicit and portable. They live in the Dockerfile, making the build process auditable and reproducible across environments. This approach pairs well with modern tools such as BuildKit, Docker Scout, and SLSA-inspired provenance tracking, and it’s supported by all major container runtimes.

Core concepts and practical patterns

A multi-stage Dockerfile uses multiple FROM instructions. Each stage can copy artifacts from earlier stages, but only the final stage produces the image’s filesystem. This lets you install build tooling, run tests, and compile code without bloating the final image.

A simple Go example: static binary, minimal runtime

Go often produces statically linked binaries, which makes it a perfect candidate for a small final image. In a production service I maintain, we compile with CGO disabled and use scratch or distroless images for the final stage.

# syntax=docker/dockerfile:1.7
# Builder stage
FROM golang:1.22-alpine AS builder

WORKDIR /src
RUN apk add --no-cache git

COPY go.mod go.sum ./
RUN go mod download

COPY . .

# Build a statically linked binary (no CGO)
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /bin/app ./cmd/app

# Test stage (optional; can be skipped in fast builds)
FROM builder AS test
RUN go test ./...

# Final stage
FROM gcr.io/distroless/static-debian12:nonroot

COPY --from=builder /bin/app /app

EXPOSE 8080
USER nonroot:nonroot
ENTRYPOINT ["/app"]

Notes on the patterns here:

  • The builder stage installs modules and builds a minimal binary with symbols stripped.
  • The test stage is optional and can be conditionally executed to avoid slowing every build.
  • The final stage uses a distroless image with no package manager and no shell, shrinking the attack surface. Nonroot user is set explicitly.

This simple structure often yields an image under 15 MB. In production, we observed faster pod startup times in Kubernetes and reduced registry storage costs. If you need a shell for debugging in dev, consider a dev-specific Dockerfile or a debug tag using a larger base image.

A Node.js example: build assets, prune dev dependencies

Node projects often need a build step (TypeScript, bundlers) and benefit from pruning devDependencies to shrink the runtime image. Multi-stage shines here by isolating the build environment.

# syntax=docker/dockerfile:1.7
# Builder stage
FROM node:20-alpine AS builder

WORKDIR /app

# Install dependencies (including devDependencies)
COPY package.json package-lock.json ./
RUN npm ci

# Copy source and build
COPY . .
RUN npm run build

# Prune devDependencies to produce a smaller node_modules
RUN npm prune --production

# Runner stage
FROM node:20-alpine AS runner

WORKDIR /app

# Copy only runtime artifacts
COPY --from=builder /app/package.json /app/package-lock.json ./
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist

# Health check and entrypoint
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node -e "require('http').get('http://localhost:8080/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"

EXPOSE 8080
USER node
CMD ["node", "dist/server.js"]

Patterns and notes:

  • npm ci gives reproducible installs; npm prune --production removes dev-only packages from the final image.
  • Copying node_modules directly (rather than running install again) speeds up builds and keeps layers small.
  • Use a healthcheck tailored to your app to help orchestrators determine readiness.

In real projects, this approach can cut a Node image from ~350 MB to ~100 MB or less, depending on the dependency tree. Add a --mount=type=cache for the npm cache under BuildKit to speed up CI:

RUN --mount=type=cache,target=/root/.npm npm ci

A Python example: compiling extensions, runtime-only deps

Python images often include compilers for building C extensions. Multi-stage lets you compile once in the builder and copy the virtual environment to a lean runtime image.

# syntax=docker/dockerfile:1.7
# Builder stage
FROM python:3.12-slim AS builder

WORKDIR /app

# Create a virtual environment to isolate runtime deps
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# Install build tools and runtime deps
RUN pip install --upgrade pip setuptools wheel
COPY requirements.txt .
RUN pip install -r requirements.txt

# Copy application code
COPY . .

# Optional: compile or build distributions if needed
# RUN python setup.py bdist_wheel

# Runner stage
FROM python:3.12-slim AS runner

WORKDIR /app

# Copy the virtual environment from the builder
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# Copy application code
COPY . .

# Run as nonroot for security
RUN groupadd -r app && useradd -r -g app app
USER app

EXPOSE 8080
CMD ["gunicorn", "--bind", "0.0.0.0:8080", "myapp.wsgi:app"]

Notes:

  • Copying the entire venv preserves exact dependency versions and avoids reinstalling at runtime.
  • Use slim base images and avoid installing build tools in the final stage.
  • For minimal images, consider distroless Python variants, but be mindful of debugging needs.

In one data pipeline service, this pattern reduced image size from ~550 MB to ~160 MB, while speeding up CI by 25% due to better layer caching.

Caching and speed considerations

Build time is a developer experience issue. Layer caching matters. Place steps that change infrequently higher in the Dockerfile. For compiled languages, cache module downloads; for Node/Python, cache package installation directories.

  • Use BuildKit’s --mount=type=cache for npm/pip caches to avoid re-downloading dependencies on every build.
  • Order Dockerfile instructions so that dependency installation comes before code copying.
  • Use docker buildx for building multi-platform images, and leverage BuildKit’s frontend for advanced features.

BuildKit reference: https://docs.docker.com/build/buildkit/

Honest evaluation: strengths, weaknesses, and tradeoffs

Multi-stage builds are powerful, but they are not a silver bullet.

Strengths:

  • Significant image size reduction and smaller attack surface.
  • Clear separation of build vs runtime concerns, encoded in version-controlled Dockerfiles.
  • Works across languages and toolchains, compatible with CI/CD pipelines.
  • Improves reproducibility by locking build steps in containers.

Weaknesses:

  • Increased Dockerfile complexity, especially for multi-language monorepos.
  • Local development may require adjustments for debugging (e.g., shell access).
  • Build times can increase if stages aren’t cached or optimized; poorly ordered steps slow things down.
  • Distroless or scratch images may complicate debugging and observability tooling.

When multi-stage builds are a good fit:

  • You need to reduce image size for deployments (cloud, Kubernetes, serverless).
  • You want to minimize runtime vulnerabilities by excluding compilers and package managers.
  • You’re comfortable structuring Dockerfiles with explicit stages.

When to be cautious:

  • You rely on runtime package installation or dynamic plugin loading in production.
  • Your team is new to containers and needs a simple, debuggable base image.
  • Your build artifacts are large and ephemeral, making stage caching tricky.

Alternatives to consider:

  • Using slim official base images without multi-stage (but retaining build tools in the runtime image).
  • Post-build tools that trim unused files (e.g., diving into distroless or custom base images).
  • Prebuilt container images with layered caching in CI (but you lose Dockerfile clarity).

For an objective comparison of base images and their security profiles, see Docker’s official image documentation and Docker Scout reports: https://docs.docker.com/trusted-content/official-images/ and https://docs.docker.com/scout/

Personal experience: lessons from the trenches

I learned the hard way that “it works on my machine” often meant “it works in my fat image.” Early on, we built Node images with node:latest, bundled devDependencies, and pushed 800 MB containers. Deploying to Kubernetes felt sluggish; rolling updates took longer than they should, and security scans flagged npm audit issues in unused dev packages.

Switching to multi-stage forced us to define what “runtime” really meant. We listed explicit entrypoints, avoided shell access in production images, and moved test suites into a separate CI step (not baked into every image). The first major win was a 65% size reduction for our API gateway. It felt like unlocking a new gear: faster image pulls, lower registry costs, and smoother rollouts.

Common mistakes I made:

  • Forgetting to copy required assets (config files, static assets) into the final stage.
  • Overusing root user in the final image, exposing more privileges than necessary.
  • Adding “just-in-case” packages to the final stage, slowly creeping size back up.
  • Not testing the final image locally with the same Docker command used in CI.

One memorable moment came when a new dependency required native bindings. The builder stage needed gcc, while the runtime didn’t. Multi-stage made it obvious: add build tools in the builder, compile, then copy the compiled module. That clarity is why I still prefer explicit stages over ad hoc optimization scripts.

Getting started: workflows, mental models, and project structure

Start with a mental model:

  • Builder stage(s): install tooling, fetch dependencies, compile, test.
  • Final stage: copy only the artifacts needed to run the app; minimize layers; set nonroot user.
  • Optional debug stage: use a larger base image with a shell for troubleshooting.

A minimal project structure for a Go service might look like this:

my-go-service/
├── cmd/
│   └── app/
│       └── main.go
├── internal/
│   └── handler/
│       └── handler.go
├── go.mod
├── go.sum
├── Dockerfile
├── .dockerignore
└── Makefile

A useful .dockerignore prevents copying unnecessary files into the build context:

.git
.gitignore
README.md
bin/
dist/
*.log
.env

Build workflow with BuildKit enabled:

# Enable BuildKit (usually default in modern Docker)
export DOCKER_BUILDKIT=1

# Build the image
docker build -t myapp:latest .

# Build with a specific target (useful for local dev vs production)
docker build --target runner -t myapp:prod .

# Run the image locally
docker run --rm -p 8080:8080 myapp:latest

In CI, you might push multi-arch images using buildx:

docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 -t myorg/myapp:latest --push .

Mental model tips:

  • Keep the final stage boring. If you need debugging, create a separate debug target.
  • Avoid environment-specific behavior in the Dockerfile; pass configuration via environment variables or mounted files.
  • Tag images with versions and git SHA for traceability.

What makes multi-stage builds stand out

  • Developer experience: The Dockerfile becomes the single source of truth for how an image is built.
  • Maintainability: Changes to build tooling or dependencies are tracked alongside application code.
  • Security: Minimal runtimes mean fewer CVEs to triage and patch.
  • Performance: Smaller images reduce registry egress and speed up scaling operations.

These advantages compound in cloud environments. Kubernetes can schedule pods faster when images are small, CI pipelines cache layers more effectively, and security teams spend less time on false positives from build-only packages. In real-world projects, multi-stage builds helped us reduce CI runtime by 20–30% and cut deployment times by a similar margin, simply by shrinking image sizes and improving cache hit rates.

Free learning resources

These resources offer practical details you can apply immediately, from syntax and caching strategies to security hardening.

Summary and recommendations

Who should use multi-stage builds:

  • Teams deploying containerized apps who want smaller images, better security, and faster CI/CD.
  • Projects compiling binaries or bundling assets that shouldn’t live in the runtime image.
  • Organizations seeking reproducible, auditable builds that don’t rely on ad hoc optimization scripts.

Who might skip or defer:

  • Very small prototypes where image size and security are not yet concerns.
  • Projects requiring runtime package installation or dynamic plugin systems that depend on a shell and package manager.
  • Teams in early learning phases who need straightforward, debuggable images and can revisit optimization later.

In practice, multi-stage builds are an easy win for most production workloads. They bring clarity to the build process, improve security posture, and reduce costs. Start with one service, measure image size and build times, then expand the pattern across your stack. The payoff shows up in everyday operations: quicker deployments, leaner registries, and fewer security surprises. That’s the kind of engineering win that doesn’t require heroics, just a few well-placed FROM statements.

Related Articles