az acr import: Copy Images Between Registries

az acr import pulls an image from another registry straight into ACR, server side, with no local docker.

Mirroring a base image from Docker Hub or another ACR is faster and more reliable than docker pull then push. import does it inside Azure.

What it does

az acr import copies an image (and its manifest) from a source registry into your ACR without pulling it onto the runner. The source can be another ACR, Docker Hub, MCR, or any reachable registry, with optional credentials.

Common usage

Terminal

# from Docker Hub into ACR
az acr import --name myregistry \
  --source docker.io/library/nginx:1.27 \
  --image base/nginx:1.27
# from another ACR
az acr import -n myregistry \
  --source other.azurecr.io/web:sha-abc123 \
  --image web:sha-abc123

Subcommands and flags

Flag	What it does
--name, -n	Destination registry short name
--source	Full source reference incl. registry and tag
--image, -t	Destination repository:tag in your ACR
--username / --password	Credentials for an authenticated source
--force	Overwrite the destination tag if it exists

In CI

Use import to seed a private ACR from a public base image once, then have builds pull from ACR to avoid Docker Hub rate limits. The federated identity needs Contributor or AcrPush on the destination registry.

Common errors in CI

"DENIED: requested access to the resource is denied" on the source means the source needs --username/--password. "TAG_ALREADY_EXISTS" or a conflict on the destination clears with --force. "ResourceNotFound" means the destination registry name or subscription is wrong.