Speeding Up Docker Builds with BuildKit: A Practical Guide

The Problem: Slow, Repetitive Builds

When a team builds a container image every time a change lands, the build often spends most of its time re‑executing steps that haven’t changed. This leads to long CI pipelines, wasted bandwidth, and developer frustration.

Why BuildKit Matters

Docker BuildKit is an optional, modern build engine that replaces the legacy builder. It introduces parallel execution, advanced caching, and new syntax that can cut build times by 70‑90% in many real‑world workloads. BuildKit works with existing Dockerfiles, so the learning curve is low.

Getting Started with BuildKit

• Verify your Docker version: docker version should list BuildKit under Engine Details. BuildKit is available from Docker 19.03 onward.
• Enable BuildKit for a session: export DOCKER_BUILDKIT=1 (Linux/macOS) or set DOCKER_BUILDKIT=1 (Windows).
• Alternatively, enable BuildKit per‑build with docker build --build-arg BUILDKIT_INLINE_CACHE=1 .. The BUILDKIT_INLINE_CACHE flag tells BuildKit to embed cache metadata into the image for reuse across builds.
• When using CI, ensure the runner can persist cache mounts (see Trade‑Offs & Caveats).

Hands‑On Example: Building a Go App with BuildKit

Below is a minimal Dockerfile that demonstrates BuildKit’s --mount=type=cache and inline cache features. The example builds a Go binary in two stages.

# syntax=docker/dockerfile:1.4
FROM golang:1.22 AS builder
WORKDIR /src

# Cache Go module downloads
RUN --mount=type=cache,target=/go/pkg/mod \
    go mod download

# Cache Go build output
RUN --mount=type=cache,target=/root/.cache/go-build \
    go build -o /app/main .

# Final minimal image
FROM gcr.io/distroless/base
COPY --from=builder /app/main /app/main
ENTRYPOINT ["/app/main"]

Build the image with inline cache enabled:

docker build \
  --build-arg BUILDKIT_INLINE_CACHE=1 \
  -t my-go-app:latest \
  .

During the first build, you’ll see progress bars and cache miss messages. Subsequent builds that only modify a README file will hit the cache for the Go module download and build steps, reducing total build time dramatically. Inspect the layers with:

docker history my-go-app:latest

Cache layers will be marked as N/A or contain inline cache metadata if the image was built with BUILDKIT_INLINE_CACHE=1.

Trade‑Offs & Caveats

CI Cache Persistence
BuildKit’s named cache mounts are not automatically stored between jobs. CI runners must be configured to cache the directories used in --mount=type=cache or to pull the image with inline cache metadata.

Registry Compatibility
Some registries do not expose inline cache metadata, limiting cross‑registry cache reuse. Verify that your registry supports the image/vnd.docker.image.rootfs.diff.tar.gzip format for cache metadata.

Secret Injection Risks
Using --secret mounts can expose sensitive data if misconfigured. Always limit secrets to the minimum scope required and never commit secret files to the repository.

Legacy Syntax Compatibility
Older Docker engines (pre‑19.03) will reject BuildKit syntax such as --mount=type=cache. Ensure all team members and CI agents run a compatible Docker version.

What to Do Next

1. Upgrade Docker to 19.03+ on all development machines and CI runners.
2. Enable BuildKit globally or per‑build and add --build-arg BUILDKIT_INLINE_CACHE=1 to your build scripts.
3. Refactor Dockerfiles to use --mount=type=cache for long‑running or repeatable steps (e.g., Go module download, Maven dependencies).
4. Configure CI to cache BuildKit named mounts or to pull images with inline cache metadata.
5. Monitor build times and compare with legacy builds using docker build --progress=plain to confirm performance gains.

By following these steps, teams can reduce build times, lower bandwidth consumption, and deliver faster feedback loops.