Skip to content

docs: document tag parameter and restructure local cache versioning #25943

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dvdksn merged 2 commits into from
Aug 28, 2026
+27 −33
Merged

docs: document tag parameter and restructure local cache versioning #25943

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dbf2f9d
docs: document tag parameter for local cache backend
sunm2n Aug 27, 2026
a342870
docs: restructure local cache versioning section
sunm2n Aug 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 27 additions & 33 deletions content/manuals/build/cache/backends/local.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ The following table describes the available CSV parameters that you can pass to
|---------------------|--------------|-------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------|
| `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][4]. |
| `tag` | `cache-to`,`cache-from` | String | `latest` | Tag of the cache manifest, see [cache versioning][4]. |
| `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][1]. |
| `oci-mediatypes` | `cache-to` | `true`,`false` | `true` | Use OCI media types in exported manifests, see [OCI media types][2]. |
Expand All @@ -47,49 +48,42 @@ build continues.

## Cache versioning

<!-- FIXME: update once https://github.com/moby/buildkit/pull/3111 is released -->
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.

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:
By default, BuildKit exports and imports the cache tagged `latest`. Use
different tags to keep multiple caches in the same directory:

```console
$ 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"
}
}
]
}
$ 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 .
```

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`](https://github.com/moby/buildkit/issues/1896)
for more information).
Exporting another cache with the same tag updates that tag to reference the new
manifest. Manifests referenced by other tags remain unchanged.

When importing cache using `--cache-from`, you can specify the `digest` parameter
to force loading an older version of the cache, for example:
Import a cache by specifying its tag:

```console
$ 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 .
$ 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:

```console
$ 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.

## Further reading

For an introduction to caching see [Docker build cache](../_index.md).
Expand Down