Prewarming images lets you explicitly trigger the downloading of container
images into the **Image Streaming** cache before a runtime client requests them.
This effectively eliminates the "cold start" latency associated with the
first pull of a new image version for workloads using
[image streaming](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/image-streaming.md.txt).

## Overview

When you push an image to Artifact Registry, it's stored in an underlying storage
system. For low-latency access, Artifact Registry also uses an **Image Streaming** cache,
which typically populates on the first pull from a client that has image
streaming enabled. For latency-sensitive workloads, like scaling up a
Google Kubernetes Engine cluster, waiting for this cache to warm up can cause delays.
Prewarming helps get images into the Image streaming cache in advance.

The **Prewarm Artifact** API lets you manually request that a specific image version or tag is precached. You also specify a retention period to ensure the image remains in the cache for a specified duration.

## Limitations

- API only: prewarming is available only using the Artifact Registry REST API. Prewarming is not available using the Google Cloud console.
- GKE only: Prewarming is only effective for GKE clusters with [Image Streaming](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/image-streaming.md.txt) enabled. Image streaming requires specific software running on the client node.
- Single artifact: you can prewarm only one artifact (version or tag) per API request.
- Multi-architecture images: Not supported. Use the specific version for an architecture image.
- Project limit: By default, the prewarm storage limit is 100 GB per project. If there isn't enough space for an image, the prewarm operation fails unless you set `force` to `true` in the request. When `force` is `true`, the least recently prewarmed images are evicted to make space for the image. To estimate how much of the limit you use, see [Check cache usage](https://docs.cloud.google.com/artifact-registry/docs/prewarm-images.md.txt#check-cache-usage).

## Before you begin

1. Enable the Artifact Registry API. For more information, see [Enable
   Artifact Registry](https://docs.cloud.google.com/artifact-registry/docs/enable-service).
2. Install the gcloud CLI to obtain authentication tokens for REST API requests.

### Required roles


To get the permissions that
you need to manage prewarmed images,

ask your administrator to grant you the
following IAM roles on the repository:

- Prewarm or remove artifacts from cache (`artifactregistry.repositories.prewarmArtifact`, `artifactregistry.repositories.removePrewarmedArtifact`): [Artifact Registry Writer](https://docs.cloud.google.com/iam/docs/roles-permissions/artifactregistry.md.txt#artifactregistry.writer) (`roles/artifactregistry.writer`)
- Check or list prewarmed artifacts (`artifactregistry.repositories.checkPrewarmedArtifact`, `artifactregistry.repositories.listPrewarmedArtifacts`): [Artifact Registry Reader](https://docs.cloud.google.com/iam/docs/roles-permissions/artifactregistry.md.txt#artifactregistry.reader) (`roles/artifactregistry.reader`)


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

This permission model ensures that only users with write access can manage the
cache state, preventing unauthorized users from overfilling the cache.
Meanwhile, users with read access can verify which artifacts are
available for streaming.

## Prewarm an image

To prewarm an image, you make a `POST` request to the `:prewarmArtifact` method of your repository.

### REST API

Reference: [`projects.locations.repositories.prewarmArtifact`](https://docs.cloud.google.com/artifact-registry/docs/reference/rest/v1/projects.locations.repositories/prewarmArtifact)

The request body has the following structure:

```json
{
  "version": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/versions/VERSION",
  "retention_days": 3
}
```

Alternatively, use a tag:

```json
{
  "tag": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/tags/TAG",
  "retention_days": 3,
  "force": true
}
```

| Field | Description |
|---|---|
| `tag` | **Optional** . The specific artifact tag to prewarm. You must specify either a `version` or a `tag`. |
| `version` | **Optional** . The specific artifact version to prewarm. You must specify either a `version` or a `tag`. |
| `retention_days` | **Optional**. The number of days to keep the artifact in the cache. If you don't specify this field, the default is 3 days. |
| `force` | **Optional** . If `true`, the system might evict older artifacts to make space for this one. |
| `stream_location` | **Optional**. The specific region where the image will be prewarmed. By default, this matches the image location. Note that multi-region configurations are not supported. If a broad region is specified, the defaults are us-central1 (US), europe-north1 (EU), and asia-east1 (Asia). |

The `:prewarmArtifact` method returns a long-running operation. When the
operation completes successfully, its `response` field contains a
`prewarmedArtifact` object. For more information about the fields in this
object, see [Check prewarm status](https://docs.cloud.google.com/artifact-registry/docs/prewarm-images.md.txt#check_prewarm_status).

#### Example: Prewarm a specific version

The following example prewarms the version `sha256:52e...` of the `nginx` package in the `my-repo` repository in "us-east1" region.

```bash
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "projects/my-project/locations/us-central1/repositories/my-repo/packages/nginx/versions/sha256:52e85304675567b5e656f5e997576a9d20c57176",
    "retention_days": 7,
    "stream_location": "us-east1"
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:prewarmArtifact"

```

#### Example: Prewarm a tag

The following example prewarms the image tagged `production` of the `my-app` package.

```bash
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "projects/my-project/locations/us-central1/repositories/my-repo/packages/my-app/tags/production",
    "force": true
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:prewarmArtifact"
```

## Check prewarm status

To check if an artifact is prewarmed, use the `:checkPrewarmedArtifact` method.
If you prewarmed the artifact in a stream location other than the repository
location, specify that location in the `stream_location` field. The following
example checks the `nginx` version that the earlier example prewarmed in
`us-east1`:

```bash
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "projects/my-project/locations/us-central1/repositories/my-repo/packages/nginx/versions/sha256:52e85304675567b5e656f5e997576a9d20c57176",
    "stream_location": "us-east1"
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:checkPrewarmedArtifact"
```

If the artifact is in the cache, the output is similar to the following:

```json
{
  "prewarmedArtifact": {
    "uri": "us-central1-docker.pkg.dev/my-project/my-repo/nginx@sha256:52e85304675567b5e656f5e997576a9d20c57176",
    "location": "us-east1",
    "expirationTime": "2026-03-21T17:04:05.123456Z",
    "state": "ACTIVE",
    "sizeBytes": "734003200",
    "createTime": "2026-03-14T17:04:05.123456Z"
  }
}
```

If the artifact isn't in the cache, for example because it expired, the
response is an empty JSON object.

The `prewarmedArtifact` object contains the following fields:

| Field | Description |
|---|---|
| `uri` | The URI of the image, which identifies the image by digest. |
| `location` | The stream location where the image is cached. |
| `state` | The caching state of the artifact: `CACHING`, `ACTIVE`, or `FAILED`. |
| `sizeBytes` | The compressed size of the artifact in bytes. This size counts toward the prewarm storage limit. |
| `createTime` | The time when the artifact was first prewarmed. |
| `expirationTime` | The time when the artifact expires from the cache, unless you prewarm it again before then. |
| `errorMessage` | The reason that caching failed. This field is set only when `state` is `FAILED`. |

Use the `state` field to determine whether the artifact is ready for
streaming:

- `CACHING`: the artifact is being cached and isn't ready for streaming.
- `ACTIVE`: the artifact is cached and ready for streaming.
- `FAILED`: caching the artifact failed. The `errorMessage` field describes the failure.

## List prewarmed artifacts

To list all prewarmed artifacts in a repository, use the `GET` method on the `prewarmedArtifacts` collection.
The following example lists all the prewarmed images under `my-repo` in `us-east1`. `stream_location` filter is required.

```bash
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo/prewarmedArtifacts?filter=stream_location=us-east1"
```

The output is similar to the following:

```json
{
  "prewarmedArtifacts": [
    {
      "uri": "us-central1-docker.pkg.dev/my-project/my-repo/nginx@sha256:52e85304675567b5e656f5e997576a9d20c57176",
      "location": "us-east1",
      "expirationTime": "2026-03-21T17:04:05.123456Z",
      "state": "ACTIVE",
      "sizeBytes": "734003200",
      "createTime": "2026-03-14T17:04:05.123456Z"
    },
    {
      "uri": "us-central1-docker.pkg.dev/my-project/my-repo/redis@sha256:4d3c2b1a0f9e8d7c6b5a49382716051f4e3d2c1b",
      "location": "us-east1",
      "expirationTime": "2026-03-17T18:30:12.654321Z",
      "state": "CACHING",
      "sizeBytes": "52428800",
      "createTime": "2026-03-14T18:30:12.654321Z"
    }
  ]
}
```

The response includes artifacts in every state, so check the `state` field to
see which artifacts are ready for streaming. Expired artifacts aren't included.

By default, each page of results contains up to 100 artifacts. To get up to
1,000 artifacts per page, set the `pageSize` query parameter. If the response
includes a `nextPageToken` value, more artifacts are available. To get the next
page, repeat the request with the `pageToken` query parameter set to the
`nextPageToken` value.

### Check cache usage

The prewarm storage limit applies to the total `sizeBytes` of the prewarmed
artifacts in your project that are in the `CACHING` or `ACTIVE` state. Expired
artifacts and artifacts in the `FAILED` state don't count toward the limit.

Each list request returns the prewarmed artifacts of one repository in one
stream location. To estimate how much of the limit your project uses in a
stream location, do the following:

1. For each repository in your project, regardless of the repository location, list all pages of prewarmed artifacts with the `filter=stream_location=LOCATION` query parameter. Replace `LOCATION` with the stream location.
2. Add up the `sizeBytes` values of the artifacts in the `CACHING` or `ACTIVE` state.

To free up space before artifacts expire,
[remove the artifacts that you no longer need](https://docs.cloud.google.com/artifact-registry/docs/prewarm-images.md.txt#remove_from_cache).

## Remove from cache

To explicitly remove an artifact from the prewarm cache, use the `:removePrewarmedArtifact` method. Use this method to free up space or when a specific image version is no longer needed in the cache.

```bash
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "projects/my-project/locations/us-central1/repositories/my-repo/packages/nginx/versions/sha256:52e85304675567b5e656f5e997576a9d20c57176"
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:removePrewarmedArtifact"
```

## What's next

- [Push and pull container images](https://docs.cloud.google.com/artifact-registry/docs/docker/pushing-and-pulling.md.txt)
- [Manage container images](https://docs.cloud.google.com/artifact-registry/docs/docker/manage-images.md.txt)
- Learn more about [Image Streaming in Google Kubernetes Engine](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/image-streaming.md.txt)