# Amazon S3 cache storage

> **Warning**
>
> This cache backend is unreleased. You can use it today, by using the
> `moby/buildkit:master` image in your Buildx driver.

The `s3` cache storage uploads your resulting build cache to
[Amazon S3 file storage service](https://aws.amazon.com/s3/), into a specified
bucket.

> **Note**
>
> This cache storage backend requires using a different driver than the default
> `docker` driver - see more information on selecting a driver
> [here](../drivers/index.md). To create a new driver (which can act as a simple
> drop-in replacement):
>
> ```console
> docker buildx create --use --driver=docker-container
> ```

## Synopsis

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

Common parameters:

- `region`: geographic location
- `bucket`: name of the S3 bucket used for caching
- `name`: name of the cache image
- `access_key_id`: access key ID, see [authentication](#authentication)
- `secret_access_key`: secret access key, see [authentication](#authentication)
- `session_token`: session token, see [authentication](#authentication)

Parameters for `--cache-to`:

- `mode`: specify cache layers to export (default: `min`), see
  [cache mode](./index.md#cache-mode)

## Authentication

`access_key_id`, `secret_access_key`, and `session_token`, if left unspecified,
are read from environment variables on the BuildKit server following the scheme
for the
[AWS Go SDK](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html).
The environment variables are read from the server, not the Buildx client.

<!-- FIXME: update once https://github.com/docker/buildx/pull/1294 is released -->

## Further reading

For an introduction to caching see
[Optimizing builds with cache management](https://docs.docker.com/build/building/cache).

For more information on the `s3` cache backend, see the
[BuildKit README](https://github.com/moby/buildkit#s3-cache-experimental).