5.2.2.3 BuildKit Registry Cache

BuildKit registry cache is a form of exportable cache stored as a dedicated artifact in a container registry, separate from any actual image, used specifically to let builds on different machines import and benefit from previously built cache without needing local disk access to where that cache was originally produced.

Exporting Cache to a Registry

A build can be configured to push its resulting cache data to a registry location, independent of pushing the actual built image.

docker buildx build \
  --cache-to type=registry,ref=myregistry/myapp:buildcache \
  -t myregistry/myapp:latest .

This pushes cache metadata to myregistry/myapp:buildcache, a location distinct from the actual application image tag.

Importing Cache From a Registry

A later build, potentially on a completely different machine, can import this previously exported cache to benefit from work already done elsewhere.

docker buildx build \
  --cache-from type=registry,ref=myregistry/myapp:buildcache \
  -t myregistry/myapp:latest .

Why a Dedicated Cache Reference Differs From Inline Cache

Unlike inline cache, which embeds cache metadata directly within the pushed application image, registry cache exports to its own separate reference, keeping the actual application image free of any added cache-related overhead.

docker images myregistry/myapp

The application image tag itself remains unaffected by the existence of a separate cache reference.

Combining Export and Import in a CI Pipeline

A typical CI pipeline both imports previously exported cache at the start of a build and exports updated cache at the end, keeping the registry cache continuously current across successive pipeline runs.

docker buildx build \
  --cache-from type=registry,ref=myregistry/myapp:buildcache \
  --cache-to type=registry,ref=myregistry/myapp:buildcache,mode=max \
  -t myregistry/myapp:latest .

Why Registry Cache Matters

Registry cache provides a robust, machine-independent caching solution well-suited to CI environments using ephemeral, disposable build agents, ensuring that meaningful build cache benefits aren't lost simply because no single build agent persists between runs.