Local cache

Table of contents

The local cache store is a simple cache option that stores your cache as files in a directory on your filesystem, using an OCI image layout for the underlying directory structure. Local cache is a good choice if you're just testing, or if you want the flexibility to self-manage a shared storage solution.

Synopsis

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=local,dest=path/to/local/dir[,parameters...] \
  --cache-from type=local,src=path/to/local/dir .

The following table describes the available CSV parameters that you can pass to --cache-to and --cache-from.

Name	Option	Type	Default	Description
`src`	`cache-from`	String		Path of the local directory where cache gets imported from.
`digest`	`cache-from`	String		Digest of manifest to import, see cache versioning.
`dest`	`cache-to`	String		Path of the local directory where cache gets exported to.
`mode`	`cache-to`	`min`,`max`	`min`	Cache layers to export, see cache mode.
`oci-mediatypes`	`cache-to`	`true`,`false`	`true`	Use OCI media types in exported manifests, see OCI media types.
`image-manifest`	`cache-to`	`true`,`false`	`false`	When using OCI media types, generate an image manifest instead of an image index for the cache image, see OCI media types.
`compression`	`cache-to`	`gzip`,`estargz`,`zstd`	`gzip`	Compression type, see cache compression.
`compression-level`	`cache-to`	`0..22`		Compression level, see cache compression.
`force-compression`	`cache-to`	`true`,`false`	`false`	Forcibly apply compression, see cache compression.
`ignore-error`	`cache-to`	Boolean	`false`	Ignore errors caused by failed cache exports.

If the src cache doesn't exist, then the cache import step will fail, but the build continues.

Cache versioning

This section describes how versioning works for caches on a local filesystem, and how you can use the digest parameter to use older versions of cache.

If you inspect the cache directory manually, you can see the resulting OCI image layout:

$ ls cache
blobs  index.json  ingest
$ cat cache/index.json | jq
{
  "schemaVersion": 2,
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.index.v1+json",
      "digest": "sha256:6982c70595cb91769f61cd1e064cf5f41d5357387bab6b18c0164c5f98c1f707",
      "size": 1560,
      "annotations": {
        "org.opencontainers.image.ref.name": "latest"
      }
    }
  ]
}

Like other cache types, local cache gets replaced on export, by replacing the contents of the index.json file. However, previous caches will still be available in the blobs directory. These old caches are addressable by digest, and kept indefinitely. Therefore, the size of the local cache will continue to grow (see moby/buildkit#1896 for more information).

When importing cache using --cache-to, you can specify the digest parameter to force loading an older version of the cache, for example:

$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=local,dest=path/to/local/dir \
  --cache-from type=local,ref=path/to/local/dir,digest=sha256:6982c70595cb91769f61cd1e064cf5f41d5357387bab6b18c0164c5f98c1f707 .

Local cache

Synopsis

Cache versioning

Further reading