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.
`tag`	`cache-to`,`cache-from`	String	`latest`	Tag of the cache manifest, 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`	`true`	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.
`reset`	`cache-to`	`true`,`false`	`false`	Delete blobs that no tag references, see cache versioning.

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

Cache versioning

A local cache directory uses an OCI image layout. Its index.json file associates tags with cache manifests, while the blobs directory stores the manifest and cache data.

By default, BuildKit exports and imports the cache tagged latest. Use different tags to keep multiple caches in the same directory:

$ docker buildx build --cache-to type=local,dest=path/to/local/dir,tag=v1 .
$ docker buildx build --cache-to type=local,dest=path/to/local/dir,tag=v2 .

Exporting another cache with the same tag updates that tag to reference the new manifest. Manifests referenced by other tags remain unchanged.

Import a cache by specifying its tag:

$ docker buildx build --cache-from type=local,src=path/to/local/dir,tag=v1 .

A digest identifies an exact cache manifest. BuildKit reports the digest of each exported manifest in the build output. Use digest instead of tag when you need a specific manifest:

$ docker buildx build \
  --cache-from type=local,src=path/to/local/dir,digest=sha256:<DIGEST> .

If you specify both digest and tag, BuildKit uses digest.

By default, updating a tag doesn't delete the blobs used by its previous manifest. The previous manifest remains available by digest, so the local cache directory grows over time.

Buildx version 0.35.0 and later supports reset=true on export, which deletes blobs that no tag references:

$ docker buildx build --cache-to type=local,dest=path/to/local/dir,reset=true .

Blobs that other tags reference are kept. Manifests that no tag references are deleted, so you can no longer import them by digest.

What can I help you with?

Local cache

Synopsis

Cache versioning

Further reading