Local cache

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.

NameOptionTypeDefaultDescription
srccache-fromStringPath of the local directory where cache gets imported from.
digestcache-fromStringDigest of manifest to import, see cache versioning.
destcache-toStringPath of the local directory where cache gets exported to.
modecache-tomin,maxminCache layers to export, see cache mode.
oci-mediatypescache-totrue,falsetrueUse OCI media types in exported manifests, see OCI media types.
compressioncache-togzip,estargz,zstdgzipCompression type, see cache compression.
compression-levelcache-to0..22Compression level, see cache compression.
force-compressioncache-totrue,falsefalseForcibly apply compression, see cache compression.
ignore-errorcache-toBooleanfalseIgnore 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 .

Further reading

For an introduction to caching see Docker build cache.

For more information on the local cache backend, see the BuildKit README.