5.2.2.4 BuildKit Cache Import

BuildKit cache import is the process of retrieving previously exported cache data — from a registry, local storage, or another supported backend — and making it available to a current build, allowing that build to potentially reuse cached layers it has never actually produced itself.

Importing From a Registry

The most common form of cache import retrieves previously exported cache from a registry reference, used heavily in CI pipelines running on fresh, disposable build agents.

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

This build attempts to reuse any matching cached layers found at the specified registry reference, even though this specific machine has never built this image before.

Importing From Local Storage

Cache exported to a local directory can similarly be imported back, useful for scenarios where cache is shared between builds through a shared filesystem rather than a registry.

docker buildx build --cache-from type=local,src=/tmp/buildcache -t myapp .

Importing From Multiple Sources

A build can specify multiple cache import sources, with BuildKit checking each for a usable match, providing flexibility for projects with multiple, possibly overlapping caching strategies.

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

Verifying Import Actually Improved Build Time

Comparing build time with and without a cache import source confirms the import is genuinely providing a benefit, rather than silently failing to match anything useful.

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

Why Cache Import Matters

Cache import is the mechanism that actually realizes the benefit of previously exported cache — without explicitly importing it, a build has no way to know that relevant cache exists elsewhere, regardless of how much useful cache might already have been produced by other builds.