--- title: Image Management description: Learn how to use Cloudflare Registry, Docker Hub, and Amazon ECR images with Containers. image: https://edgetunnel-b2h.pages.dev/dev-products-preview.png --- > Documentation Index > Fetch the complete documentation index at: https://edgetunnel-b2h.pages.dev/containers/llms.txt > Use this file to discover all available pages before exploring further. [Skip to content](#%5Ftop) # Image Management ## Push images during `wrangler deploy` When running `wrangler deploy`, if you set the `image` attribute in your [Wrangler configuration](https://edgetunnel-b2h.pages.dev/workers/wrangler/configuration/#containers) to a path to a Dockerfile, Wrangler will build your container image locally using Docker, then push it to a registry run by Cloudflare. This registry is integrated with your Cloudflare account and is backed by [R2](https://edgetunnel-b2h.pages.dev/r2/). All authentication is handled automatically by Cloudflare both when pushing and pulling images. Just provide the path to your Dockerfile: * [ wrangler.jsonc ](#tab-panel-8539) * [ wrangler.toml ](#tab-panel-8540) **JSONC** ```jsonc { "containers": [ { "image": "./Dockerfile" } ] } ``` **TOML** ```toml [[containers]] image = "./Dockerfile" ``` And deploy your Worker with `wrangler deploy`. No other image management is necessary. On subsequent deploys, Wrangler will only push image layers that have changed, which saves space and time. Note Docker or a Docker-compatible CLI tool must be running for Wrangler to build and push images. This is not necessary if you are using a pre-built image, as described below. ## Use pre-built container images Containers support images from the Cloudflare managed registry at `registry.cloudflare.com`, [Docker Hub ↗](https://hub.docker.com/), [Amazon ECR ↗](https://aws.amazon.com/ecr/), and [Google Artifact Registry ↗](https://cloud.google.com/artifact-registry). Note Cloudflare does not cache images pulled from Docker Hub, Amazon ECR, or Google Artifact Registry. Docker Hub pulls may be subject to Docker Hub pull limits or fair-use restrictions. Pulling images from Amazon ECR or Google Artifact Registry may incur cloud provider egress charges. ### Use public Docker Hub images To use a public Docker Hub image, set `image` to a fully qualified Docker Hub image reference in your Wrangler configuration. For example: * [ wrangler.jsonc ](#tab-panel-8541) * [ wrangler.toml ](#tab-panel-8542) **JSONC** ```jsonc { "containers": [ { "image": "docker.io//:" } ] } ``` **TOML** ```toml [[containers]] image = "docker.io//:" ``` Public Docker Hub images do not require registry configuration. Private Docker Hub images use the private registry configuration flow described next. If Docker Hub credentials have been configured, those credentials are used to pull both public and private images. Note Official Docker Hub images use the `library` namespace. For example, use `docker.io/library/:` instead of `docker.io/:`. ### Configure private registry credentials To use a private image from Docker Hub, Amazon ECR, or Google Artifact Registry, run [wrangler containers registries configure](https://edgetunnel-b2h.pages.dev/workers/wrangler/commands/containers/#containers-registries-configure) for the registry domain. Wrangler prompts for the secret and stores it in [Secrets Store](https://edgetunnel-b2h.pages.dev/secrets-store). If you do not already have a Secrets Store store, Wrangler prompts you to create one first. Use `--secret-name` to name or reuse a secret, `--secret-store-id` to target a specific Secrets Store store, and `--skip-confirmation` for non-interactive runs. In CI or scripts, pass the secret through `stdin`. ### Use private Docker Hub images Configure Docker Hub in Wrangler using these values: * registry domain: `docker.io` * username flag: `--dockerhub-username=` * secret: Docker Hub personal access token with read-only access To create a Docker Hub personal access token: 1. Sign in to [Docker Home ↗](https://app.docker.com/). 2. Go to **Account settings** \> **Personal access tokens**. 3. Select **Generate new token**. 4. Give the token **Read** access, then copy the token value. Interactive: npm yarn pnpm ``` npx wrangler containers registries configure docker.io --dockerhub-username= ``` ``` yarn wrangler containers registries configure docker.io --dockerhub-username= ``` ``` pnpm wrangler containers registries configure docker.io --dockerhub-username= ``` CI or scripts: ```bash printf '%s' "$DOCKERHUB_PAT" | npx wrangler containers registries configure docker.io --dockerhub-username= --secret-name= --skip-confirmation ``` After you configure the registry, use the same fully qualified Docker Hub image reference shown above. ### Use private Amazon ECR images Configure Amazon ECR in Wrangler using these values: * registry domain: `.dkr.ecr..amazonaws.com` * access key flag: `--aws-access-key-id=` * secret: matching AWS secret access key Public ECR images are not supported. To generate the required credentials, create an IAM user with a read-only policy. The following example grants access to all image repositories in AWS account `123456789012` in `us-east-1`. ```json { "Version": "2012-10-17", "Statement": [ { "Action": ["ecr:GetAuthorizationToken"], "Effect": "Allow", "Resource": "*" }, { "Effect": "Allow", "Action": [ "ecr:BatchCheckLayerAvailability", "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage" ], // arn:${Partition}:ecr:${Region}:${Account}:repository/${Repository-name} "Resource": [ "arn:aws:ecr:us-east-1:123456789012:repository/*" // "arn:aws:ecr:us-east-1:123456789012:repository/example-repo" ] } ] } ``` After you create the IAM user, use its credentials to [configure the registry in Wrangler](https://edgetunnel-b2h.pages.dev/workers/wrangler/commands/containers/#containers-registries-configure). Wrangler prompts you to create a Secrets Store store if one does not already exist, then stores the secret there. Interactive: npm yarn pnpm ``` npx wrangler containers registries configure .dkr.ecr..amazonaws.com --aws-access-key-id= ``` ``` yarn wrangler containers registries configure .dkr.ecr..amazonaws.com --aws-access-key-id= ``` ``` pnpm wrangler containers registries configure .dkr.ecr..amazonaws.com --aws-access-key-id= ``` CI or scripts: ```bash printf '%s' "$AWS_SECRET_ACCESS_KEY" | npx wrangler containers registries configure .dkr.ecr..amazonaws.com --aws-access-key-id= --secret-name= --skip-confirmation ``` After you configure the registry, use the fully qualified Amazon ECR image reference in your Wrangler configuration: * [ wrangler.jsonc ](#tab-panel-8543) * [ wrangler.toml ](#tab-panel-8544) **JSONC** ```jsonc { "containers": [ { "image": ".dkr.ecr..amazonaws.com/:" } ] } ``` **TOML** ```toml [[containers]] image = ".dkr.ecr..amazonaws.com/:" ``` ### Use private Google Artifact Registry images Configure Google Artifact Registry in Wrangler using these values: * registry domain: `-docker.pkg.dev` * Google service account email flag: `--gar-email=` * secret: the service account JSON key The public credential is the service account email, supplied with `--gar-email`. It must match the `client_email` field in the service account key. The private credential is the service account JSON key. Provide it through `stdin` (a file path, raw JSON, or base64) or the interactive prompt (a file path or base64). Wrangler stores the key base64-encoded in Secrets Store. Warning Only `*-docker.pkg.dev` hosts are supported. Container Registry hosts such as `gcr.io` and `*.gcr.io` are not supported, because Google has shut down Container Registry. To generate the required credentials, create a service account with the **Artifact Registry Reader** role and download its JSON key: 1. In the [Google Cloud console ↗](https://console.cloud.google.com), go to **IAM & Admin** \> **Service Accounts**. 2. Select **Create service account**, then enter a name, ID, and optional description. 3. Grant the service account the **Artifact Registry Reader** role, then select **Done**. 4. Select the service account, then open the **Keys** tab. 5. Select **Add key** \> **Create new key**, choose **JSON**, then select **Create**. The key file downloads to your machine. Interactive: Wrangler prompts for the key, where you enter a file path or base64-encoded JSON: npm yarn pnpm ``` npx wrangler containers registries configure -docker.pkg.dev --gar-email= ``` ``` yarn wrangler containers registries configure -docker.pkg.dev --gar-email= ``` ``` pnpm wrangler containers registries configure -docker.pkg.dev --gar-email= ``` CI or scripts: Pipe the key through `stdin` (the key contents as raw JSON or base64, or a path to the key file) ```bash cat | npx wrangler containers registries configure -docker.pkg.dev --gar-email= --secret-name= --skip-confirmation ``` If you have already stored the key in Secrets Store, reference the existing secret and omit the key: ```bash npx wrangler containers registries configure -docker.pkg.dev --gar-email= --secret-name= --skip-confirmation ``` After you configure the registry, use the fully qualified Google Artifact Registry image reference in your Wrangler configuration: * [ wrangler.jsonc ](#tab-panel-8545) * [ wrangler.toml ](#tab-panel-8546) **JSONC** ```jsonc { "$schema": "./node_modules/wrangler/config-schema.json", "containers": [ { "image": "-docker.pkg.dev///:" } ] } ``` **TOML** ```toml [[containers]] image = "-docker.pkg.dev///:" ``` ### Use images from other registries If you want to use a pre-built image from another registry provider, first make sure it exists locally, then push it to the Cloudflare Registry: ```bash docker pull docker tag : ``` Wrangler provides a command to push images to the Cloudflare Registry: npm yarn pnpm ``` npx wrangler containers push : ``` ``` yarn wrangler containers push : ``` ``` pnpm wrangler containers push : ``` Or, you can use the `-p` flag with `wrangler containers build` to build and push an image in one step: npm yarn pnpm ``` npx wrangler containers build -p -t . ``` ``` yarn wrangler containers build -p -t . ``` ``` pnpm wrangler containers build -p -t . ``` This will output an image registry URI that you can then use in your Wrangler configuration: * [ wrangler.jsonc ](#tab-panel-8547) * [ wrangler.toml ](#tab-panel-8548) **JSONC** ```jsonc { "containers": [ { "image": "registry.cloudflare.com//:" } ] } ``` **TOML** ```toml [[containers]] image = "registry.cloudflare.com//:" ``` Note With `wrangler dev`, image references from the Cloudflare Registry, Docker Hub, Amazon ECR, and Google Artifact Registry are supported in local development. With `vite dev`, image references from external registries such as Docker Hub, Amazon ECR, and Google Artifact Registry are supported, but `vite dev` cannot pull directly from the Cloudflare Registry. If you use a private Docker Hub, Amazon ECR, or Google Artifact Registry image in local development, authenticate to that registry locally, for example with `docker login`. ## Push images with CI To use an image built in a continuous integration environment, install `wrangler` then build and push images using either `wrangler containers build` with the `--push` flag, or using the `wrangler containers push` command. ## Registry limits Images are limited in size by available disk of the configured [instance type](https://edgetunnel-b2h.pages.dev/containers/platform-details/limits/#instance-types) for a Container. Delete images with `wrangler containers images delete` to free up space, but reverting a Worker to a previous version that uses a deleted image will then error. ```json {"@context":"https://schema.org","@type":"WebPage","@id":"https://edgetunnel-b2h.pages.dev/containers/platform-details/image-management/#page","headline":"Image Management · Cloudflare Containers docs","description":"Learn how to use Cloudflare Registry, Docker Hub, and Amazon ECR images with Containers.","url":"https://edgetunnel-b2h.pages.dev/containers/platform-details/image-management/","inLanguage":"en","image":"https://edgetunnel-b2h.pages.dev/dev-products-preview.png","dateModified":"2026-07-01","publisher":{"@type":"Organization","name":"Cloudflare","url":"https://www.cloudflare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://edgetunnel-b2h.pages.dev/#website","name":"Cloudflare Docs","url":"https://edgetunnel-b2h.pages.dev/"}} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/containers/","name":"Containers"}},{"@type":"ListItem","position":3,"item":{"@id":"/containers/platform-details/","name":"Platform Reference"}},{"@type":"ListItem","position":4,"item":{"@id":"/containers/platform-details/image-management/","name":"Image Management"}}]} ```