Home • Explore • Blog • Models • CI
☰



docker
1st chunk of `content/manuals/build/cache/backends/registry.md`
5a3cda42c067125f327f339a48e31fc1367d4523c5d601a2000000010000091e
---
title: Registry cache
description: Manage build cache with an OCI registry
keywords: build, buildx, cache, backend, registry
aliases:
  - /build/building/cache/backends/registry/
---

The `registry` cache storage can be thought of as an extension to the `inline`
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 `max` mode, instead of only the
  final stage.
- It works with other exporters for more flexibility, instead of only the
  `image` exporter.

This cache storage backend is not supported with the default `docker` driver.
To use this feature, create a new builder using a different driver. See
[Build drivers](/manuals/build/builders/drivers/_index.md) for more information.

## Synopsis

Unlike the simpler `inline` cache, the `registry` cache supports several
configuration parameters:

```console
$ 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
`--cache-to` and `--cache-from`.

| Name                | Option                  | Type                    | Default | Description                                                                                                                     |
|---------------------|-------------------------|-------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------|
| `ref`               | `cache-to`,`cache-from` | String                  |         | Full name of the cache image to import.                                                                                         |
| `mode`              | `cache-to`              | `min`,`max`             | `min`   | Cache layers to export, see [cache mode][1].                                                                                    |
Title: Registry Cache in Buildx
Summary
The `registry` cache storage in Buildx offers advantages over the `inline` cache, such as separating the cache from the image, efficient caching of multi-stage builds, and compatibility with various exporters. It requires a driver other than the default `docker` driver. Configuration parameters include `ref` (cache image name) and `mode` (`min` or `max` for cache layers to export).