✦ For everyone, free.

Practical knowledge for real and everyday life

Home

5.2.2.5 BuildKit Cache Export

A focused guide to BuildKit Cache Export, connecting core concepts with practical Docker and container operations.

BuildKit cache export is the process of writing a build's resulting cache data to a specified destination — a registry, local storage — making it available for a later build, potentially on an entirely different machine, to import and reuse.

Exporting to a Registry

The most common destination for cache export in CI environments is a dedicated registry reference, kept separate from the actual application image.

docker buildx build --cache-to type=registry,ref=myregistry/myapp:buildcache -t myapp .
Choosing an Export Mode

BuildKit supports different export modes controlling how much cache data is actually preserved — a minimal mode exports only what is needed for the final image, while a maximal mode preserves cache for every intermediate layer, including ones not present in the final result.

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

The mode=max option preserves more cache data, useful when intermediate build stages (such as those in a multi-stage build) might themselves be reused by a future build even if their specific output isn't part of the current final image.

Exporting to Local Storage

Cache can also be exported to a local directory, useful for scenarios involving a shared filesystem between build agents rather than a registry.

docker buildx build --cache-to type=local,dest=/tmp/buildcache -t myapp .
Combining Export With Import in the Same Build

A typical pipeline both imports existing cache and exports updated cache within the same build invocation, keeping the cache continuously current across successive runs.

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

Without explicitly exporting cache to a shared destination, any caching benefit produced by a build remains local to that specific machine — cache export is what makes that benefit available to other machines and future, separate build runs.

Related content