Buildx Cache Configuration: Mode, Compression, and OCI Media Types

backend types. Additionally, the different backend types support specific parameters as well. See the detailed page about each backend type for more information about which configuration parameters apply. The common parameters described here are: - [Cache mode](#cache-mode) - [Cache compression](#cache-compression) - [OCI media type](#oci-media-types) ### Cache mode When generating a cache output, the `--cache-to` argument accepts a `mode` option for defining which layers to include in the exported cache. This is supported by all cache backends except for the `inline` cache. Mode can be set to either of two options: `mode=min` or `mode=max`. For example, to build the cache with `mode=max` with the registry backend: ```console $ docker buildx build --push -t <registry>/<image> \ --cache-to type=registry,ref=<registry>/<cache-image>,mode=max \ --cache-from type=registry,ref=<registry>/<cache-image> . ``` This option is only set when exporting a cache, using `--cache-to`. When importing a cache (`--cache-from`) the relevant parameters are automatically detected. In `min` cache mode (the default), only layers that are exported into the resulting image are cached, while in `max` cache mode, all layers are cached, even those of intermediate steps. While `min` cache is typically smaller (which speeds up import/export times, and reduces storage costs), `max` cache is more likely to get more cache hits. Depending on the complexity and location of your build, you should experiment with both parameters to find the results that work best for you. ### Cache compression The cache compression options are the same as the [exporter compression options](../../exporters/_index.md#compression). This is supported by the `local` and `registry` cache backends. For example, to compress the `registry` cache with `zstd` compression: ```console $ docker buildx build --push -t <registry>/<image> \ --cache-to type=registry,ref=<registry>/<cache-image>,compression=zstd \ --cache-from type=registry,ref=<registry>/<cache-image> . ``` ### OCI media types The cache OCI options are the same as the [exporter OCI options](../../exporters/_index.md#oci-media-types). These are supported by the `local` and `registry` cache backends. For example, to export OCI media type cache, use the `oci-mediatypes` property: ```console $ docker buildx build --push -t <registry>/<image> \ --cache-to type=registry,ref=<registry>/<cache-image>,oci-mediatypes=true \ --cache-from type=registry,ref=<registry>/<cache-image> . ``` This property is only meaningful with the `--cache-to` flag. When fetching cache, BuildKit will auto-detect the correct media types to use. By default, the OCI media type generates an image index for the cache image. Some OCI registries, such as Amazon ECR, don't support the image index media type: `application/vnd.oci.image.index.v1+json`. If you export cache images to ECR, or any other registry that doesn't support image indices, set the `image-manifest` parameter to `true` to generate a single image manifest instead of an image index for the cache image: ```console $ docker buildx build --push -t <registry>/<image> \ --cache-to type=registry,ref=<registry>/<cache-image>,oci-mediatypes=true,image-manifest=true \ --cache-from type=registry,ref=<registry>/<cache-image> . ``` > [!NOTE] > Since BuildKit v0.21, `image-manifest` is enabled by default.

This section details common configuration options for Buildx cache exports, including cache mode (min/max), compression (e.g., zstd), and OCI media types. `min` cache mode exports only layers included in the final image, while `max` caches all layers, including intermediate ones. OCI media type support allows exporting cache in OCI format, with options to generate an image index or a single image manifest (required for registries like Amazon ECR that don't support image indices). Since BuildKit v0.21, `image-manifest` is enabled by default.