registry cache storage can be thought of as an extension to the
cache. Unlike the
inline cache, the
registry cache is entirely separate from
the image, which allows for more flexible usage -
registry-backed cache can do
everything that the inline cache can do, and more:
- Allows for separating the cache and resulting image artifacts so that you can distribute your final image without the cache inside.
- It can efficiently cache multi-stage builds in
maxmode, instead of only the final stage.
- It works with other exporters for more flexibility, instead of only the
This cache storage backend is not supported with the default
To use this feature, create a new builder using a different driver. See
Build drivers for more information.
Unlike the simpler
inline cache, the
registry cache supports several
$ docker buildx build --push -t <registry>/<image> \ --cache-to type=registry,ref=<registry>/<cache-image>[,parameters...] \ --cache-from type=registry,ref=<registry>/<cache-image> .
The following table describes the available CSV parameters that you can pass to
|String||Full name of the cache image to import.|
|String||Path of the local directory where cache gets exported to.|
|Cache layers to export, see cache mode.|
|Use OCI media types in exported manifests, see OCI media types.|
|Compression type, see cache compression.|
|Compression level, see cache compression.|
|Forcibly apply compression, see cache compression.|
|Boolean||Ignore errors caused by failed cache exports.|
You can choose any valid value for
ref, as long as it's not the same as the
target location that you push your image to. You might choose different tags
foo/bar:build-cache), separate image names (e.g.
foo/bar-cache), or even different repositories (e.g.
ghcr.io/foo/bar). It's up to you to decide the
strategy that you want to use for separating your image from your cache images.
--cache-from target doesn't exist, then the cache import step will
fail, but the build continues.
For an introduction to caching see Optimizing builds with cache.
For more information on the
registry cache backend, see the