5.2 BuildKit
A focused guide to BuildKit, connecting core concepts with practical Docker and container operations.
BuildKit is the modern image build engine that powers docker build, replacing the legacy builder with a more efficient architecture that supports parallel execution, advanced caching, and build-time features that the legacy builder could not provide.
Why BuildKit Replaced the Legacy Builder
The legacy builder executed a Dockerfile's instructions in strict sequence, even when some of them had no actual dependency on each other, missing significant opportunities for parallelism. BuildKit instead constructs a dependency graph of build steps and executes independent steps concurrently wherever possible.
FROM golang:1.22 AS backend-build
RUN go build -o backend .
FROM node:20 AS frontend-build
RUN npm run build
BuildKit can build these two independent stages concurrently, since neither depends on the other's output; the legacy builder would have processed them strictly one after another.
Enabling BuildKit
In modern versions of Docker, BuildKit is enabled by default; it can also be explicitly controlled through an environment variable or daemon configuration if needed.
DOCKER_BUILDKIT=1 docker build -t myapp .
New Capabilities BuildKit Introduced
BuildKit introduced several capabilities not available in the legacy builder, including cache mounts for persisting package manager downloads across builds, and secret mounts for using sensitive values during a build without baking them into the resulting image.
RUN --mount=type=secret,id=npm_token \
npm config set //registry.npmjs.org/:_authToken=$(cat /run/secrets/npm_token) \
&& npm install
Verifying BuildKit Is Actually in Use
Build output produced by BuildKit looks distinctly different from the legacy builder's output, making it straightforward to confirm which engine is actually being used for a given build.
docker build -t myapp .
Why BuildKit Matters
BuildKit's architecture provides meaningfully faster builds through parallelism and improved caching, along with new capabilities like secret mounts that directly address previously awkward problems — making it foundational to how modern Docker builds operate, even when its presence is mostly invisible to a typical user.