wrangler containers configure DockerHub credentials and reference DockerHub images
Introduced 2026-03-03 · score 0.97
HOW TO USE IT
For a private Docker Hub image, configure credentials for `docker.io` with a read-only Docker Hub personal access token, then set the container `image` to its fully qualified Docker Hub reference. Local development with a private image also requires authenticating to the registry locally.
printf '%s' "$DOCKERHUB_PAT" | npx wrangler containers registries configure docker.io --dockerhub-username=<YOUR_DOCKERHUB_USERNAME> --secret-name=<SECRET_NAME> --skip-confirmation{"containers":[{"image":"docker.io/<NAMESPACE>/<REPOSITORY>:<TAG>"}]}WHY THIS HELPS
Configure a Worker container to use a private DockerHub image during development or deployment.
REQUIREMENTS AND LIMITATIONS
- Version: 4.70.0
- DOMAIN (`docker.io`) (required): Registry domain to configure.
- --dockerhub-username: Docker Hub username; use with `docker.io`. The secret is a Docker Hub personal access token.
- --secret-name: Name Wrangler stores the registry credentials under.
- --skip-confirmation: Use for non-interactive runs.
- --secret-store-id: ID of the Secrets Store to use for registry credentials.
- Credential flags: `--dockerhub-username`, `--aws-access-key-id`, and `--gar-email` are mutually exclusive; use the flag matching the registry.
- containers[].image (required): For this task, set it to `docker.io/<NAMESPACE>/<REPOSITORY>:<TAG>`.
- Prerequisite: Use a Docker Hub personal access token with read-only access for the private image.
- Prerequisite: Wrangler stores the secret in Secrets Store; if no Secrets Store exists, Wrangler prompts to create one.
- Prerequisite: For a private Docker Hub image in local development, authenticate to the registry locally, for example with `docker login`.
- Docs conflict: Current docs say the `containers` configuration is an array (`containers: [{"image": ...}]`), while the release note example shows an object. Used the documented current configuration shape. Current docs scope direct external registry references and configured credentials to the `default` scheduling policy; `durable_object` requires pushing the image to Cloudflare's managed registry.
FIRST-PARTY EVIDENCE
- https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%404.70.0
- https://developers.cloudflare.com/containers/guides/image-management/
- https://developers.cloudflare.com/workers/wrangler/commands/containers/
Check the installed version and the source before using it. Entry JSON