5.2.2.2 BuildKit Inline Cache

BuildKit inline cache embeds cache metadata directly within a pushed image itself, allowing a separate build — potentially on an entirely different machine — to import and reuse that cache simply by referencing the previously pushed image, without needing a separate, dedicated cache storage location.

How Inline Cache Differs From Registry Cache Export

A dedicated cache export pushes cache data to its own separate location in a registry; inline cache instead embeds the relevant cache metadata directly alongside the image's own layers when it is pushed, avoiding the need for a separate cache artifact entirely.

docker build --build-arg BUILDKIT_INLINE_CACHE=1 -t myregistry/myapp:latest .
docker push myregistry/myapp:latest

A later build elsewhere can import this cache simply by referencing the previously pushed image itself.

docker build --cache-from myregistry/myapp:latest -t myregistry/myapp:latest .

Why This Convenience Comes With a Trade-off

Embedding cache metadata directly in the pushed image means that image carries slightly more data than it strictly needs to in order to run — a trade-off between operational simplicity (no separate cache artifact to manage) and a marginally larger pushed image.

docker images myregistry/myapp

When Inline Cache Is a Good Fit

Inline cache works well for projects that already push every build to a registry and want a low-effort way to benefit from cross-machine cache reuse without setting up a separate, dedicated cache storage location.

docker build --cache-from myregistry/myapp:latest --build-arg BUILDKIT_INLINE_CACHE=1 -t myregistry/myapp:latest .
docker push myregistry/myapp:latest

Why Inline Cache Matters

Inline cache provides a notably low-friction path to cross-machine cache reuse, particularly appealing for projects that want the benefit of shared cache without introducing a separate piece of cache infrastructure to manage and maintain alongside the images themselves.