BuildKit

BuildKit is the build engine that powers docker build. It follows a client/daemon architecture: the buildkitd daemon runs the build execution engine, while buildctl (or a higher-level client such as Docker Buildx) sends build requests over a gRPC API. Builds are represented internally as LLB, a Protobuf-encoded, content-addressed intermediate representation that lets BuildKit resolve build-step dependencies concurrently, cache each step efficiently, and support build definitions beyond Dockerfile syntax.

Frontends translate a build definition — Dockerfile syntax, or an alternate language like HLB or Earthfile — into LLB; BuildKit then schedules and executes the resulting graph across pluggable workers (an OCI/runc worker or a containerd worker), exporting results as registry images, OCI/Docker tarballs, local directories, or straight into a containerd image store. Because the daemon exposes a stable gRPC API and LLB is vendor-neutral, projects like Docker Buildx, Dagger, Earthly, envd, and Gitpod build directly on top of BuildKit rather than re-implementing image builds themselves.

What You Get

• buildkitd daemon - a long-running build server exposing a gRPC API, with OCI (runc) and containerd worker backends.
• buildctl CLI - a low-level client for driving builds, inspecting the build cache, and managing workers directly against a buildkitd instance.
• LLB intermediate representation - a Protobuf-encoded, content-addressable build graph that any frontend (Dockerfile, Buildpacks, HLB, Earthfile, and others) can compile to.
• Pluggable frontends and exporters - built-in Dockerfile (dockerfile.v0) and gateway (gateway.v0) frontends, plus exporters for registries, local directories, tarballs, and containerd image stores.
• Distributed and remote build caching - inline, registry, local directory, S3, Azure Blob Storage, and GitHub Actions cache backends for sharing build cache across machines and CI runs.

Common Use Cases

• Powering docker build - Docker Engine and Docker Buildx use BuildKit as the default build backend for building images from Dockerfiles.
• Building custom, non-Dockerfile pipelines - tools like Earthly, Dagger, and envd define their own high-level build languages that compile down to LLB and execute on BuildKit.
• CI build acceleration - teams run buildkitd as a shared remote builder with registry- or S3-backed cache exporters so CI pipelines reuse cached layers across runs and machines.
• Rootless and sandboxed image builds - platforms like Gitpod, Okteto, and Namespace embed BuildKit to give untrusted or multi-tenant users the ability to build images without root privileges on the host.

Under The Hood

Architecture BuildKit is organized as a clean client/daemon pipeline: client/llb lets callers build a Protobuf-encoded LLB graph, control/control.go exposes that as a gRPC control service implemented by buildkitd (cmd/buildkitd/main.go), frontend/ (Dockerfile and gateway frontends) translates higher-level build definitions into LLB, solver/ (scheduler.go, cachekey.go, jobs.go) resolves the dependency graph concurrently against a content-addressed cache, and worker/ (with base, runc, and containerd backends) actually executes each step before exporter/ ships the result out. Each layer is a distinct, independently testable Go package, so swapping a worker backend or adding an exporter does not require touching the scheduler or frontend code — this separation is what lets downstream projects (Buildx, Dagger, Earthly) build on the same daemon without forking it.

Tech Stack Written in Go (go 1.26 per go.mod) with the build graph serialized as Protobuf (solver/pb), the daemon communicates over gRPC (google.golang.org/grpc) and executes steps via runc/crun or containerd (including its snapshotter ecosystem — stargz-snapshotter, nydus-snapshotter, fuse-overlayfs-snapshotter). Cloud cache backends are implemented against the AWS and Azure Go SDKs (S3, Azure Blob Storage). Observability runs through OpenTelemetry, and dependencies are vendored (modules-download-mode: vendor) for reproducible, offline-capable builds.

Code Quality The repository carries an extensive test suite (hundreds of _test.go files across client, solver, worker, and frontend) alongside a strict .golangci.yml enabling linters such as errorlint, errname, gosec, bodyclose, ineffassign, and depguard. Errors flow through a dedicated errdefs package that wraps failures in typed markers (Internal, System) so callers can classify errors with errors.As rather than string-matching. CI is split across multiple dedicated GitHub Actions workflows (buildkit.yml, frontend.yml, dockerd.yml, test-os.yml, plus a zizmor.yml workflow scanning the Actions config itself for security issues), reflecting a mature, security-conscious maintenance process for a project embedded in Docker’s build path.

API Design The primary integration surface is client/llb, a fluent, chainable Go API (llb.Image(...).Run(...).Root()) for constructing build graphs programmatically, documented via a pkg.go.dev badge and exercised by the examples/ directory’s runnable samples. Most users, however, never touch this API directly — they drive builds through buildctl or a Dockerfile, and external frontends can be written in any language by implementing the gateway.v0 gRPC contract rather than importing Go code at all. This makes BuildKit’s core LLB API expressive but low-level; the ergonomics investment is concentrated in the Dockerfile/gateway frontend layer rather than the raw client library.