Amazon S3 cache


This is an experimental feature. The interface and behavior are unstable and may change in future releases.

The s3 cache storage uploads your resulting build cache to Amazon S3 file storage service or other S3-compatible services, such as MinIO.

This cache storage backend is not supported with the default docker driver. To use this feature, create a new builder using a different driver. See Build drivers for more information.


$ docker buildx build --push -t <user>/<image> \
  --cache-to type=s3,region=<region>,bucket=<bucket>,name=<cache-image>[,parameters...] \
  --cache-from type=s3,region=<region>,bucket=<bucket>,name=<cache-image> .

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

regioncache-to,cache-fromStringRequired. Geographic location.
bucketcache-to,cache-fromStringRequired. Name of the S3 bucket.
namecache-to,cache-fromStringName of the cache image.
endpoint_urlcache-to,cache-fromStringEndpoint of the S3 bucket.
blobs_prefixcache-to,cache-fromStringPrefix to prepend to blob filenames.
manifests_prefixcache-to,cache-fromStringPrefix to prepend on manifest filenames.
use_path_stylecache-to,cache-fromBooleanfalseWhen true, uses bucket in the URL instead of hostname.
access_key_idcache-to,cache-fromStringSee authentication.
secret_access_keycache-to,cache-fromStringSee authentication.
session_tokencache-to,cache-fromStringSee authentication.
modecache-tomin,maxminCache layers to export, see cache mode.
ignore-errorcache-toBooleanfalseIgnore errors caused by failed cache exports.


Buildx can reuse existing AWS credentials, configured either using a credentials file or environment variables, for pushing and pulling cache to S3. Alternatively, you can use the access_key_id, secret_access_key, and session_token attributes to specify credentials directly on the CLI.

Refer to AWS Go SDK, Specifying Credentials for details about authentication using environment variables and credentials file.

Further reading

For an introduction to caching see Docker build cache.

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