Edit

Import container images to a container registry

You can easily import (copy) container images to an Azure container registry without using Docker commands. For example, you can import images from a development registry to a production registry, or copy base images from a public registry.

Azure Container Registry handles many common scenarios to copy images and other artifacts from an existing registry:

  • Import images from a public registry.

  • Import images or OCI artifacts, including Helm 3 charts, from another Azure container registry in the same Azure subscription, Azure tenant, or across subscriptions and tenants.

  • Import images from a non-Azure private container registry.

Importing images into an Azure container registry has the following benefits compared to using Docker CLI commands:

  • If your client environment doesn't need a local Docker installation, you can import any container image, regardless of the supported OS type.

  • If you import multi-architecture images (such as official Docker images), images for all architectures and platforms specified in the manifest list get copied.

  • If you have access to the target registry, you don't require the registry's public endpoint.

Important

Importing images requires external registry support RFC 7233. To avoid failures, use a registry that supports RFC 7233 ranges while using the az acr import command with the registry URI.

Limitations

  • The maximum number of manifests for an imported image is 50.

To import container images, run the Azure CLI in Azure Cloud Shell or locally.

Note

If you need to distribute identical container images across multiple Azure regions, Azure Container Registry also supports geo-replication. By geo-replicating a registry (Premium service tier required), you can serve multiple regions with identical image and tag names from a single registry.

Important

To import to or from a network-restricted Azure container registry, the restricted registry must allow access by trusted services to bypass the network. By default, the setting is enabled, so import works. If you create a registry with a private endpoint or with registry firewall rules and don't enable the setting, import fails.

Prerequisites

If you don't already have an Azure container registry, create a registry. For steps, see Quickstart: Create a private container registry using the Azure CLI.

To import an image to an Azure Container Registry, your identity must have permissions to trigger imports on the target registry (Container Registry Data Importer and Data Reader role). See Azure Container Registry Entra permissions and roles overview.

Import container images from a public registry

Important

To import from a public registry to a network-restricted Azure container registry, the restricted registry must allow access by trusted services to bypass the network. By default, this setting is enabled, so import works. If you disable this setting in a newly created registry with a private endpoint or with registry firewall rules, import fails.

Import container images from Docker Hub

For example, use the az acr import command to import the multi-architecture hello-world:latest image from Docker Hub to a registry named myregistry. Because hello-world is an official image from Docker Hub, this image is in the default library repository. Include the repository name and optionally a tag in the value of the --source image parameter. (You can optionally identify an image by its manifest digest instead of by tag, which guarantees a particular version of an image.)

az acr import \
  --name myregistry \
  --source docker.io/library/hello-world:latest \
  --image hello-world:latest

You can verify that multiple manifests are associated with this image by running the az acr manifest list-metadata command:

az acr manifest list-metadata \
  --name hello-world \
  --registry myregistry

To import an artifact by digest without adding a tag:

az acr import \
   --name myregistry \
   --source docker.io/library/hello-world@sha256:abc123 \
   --repository hello-world

If you have a Docker Hub account, use the credentials when importing an image from Docker Hub. Pass the Docker Hub user name and the password or a personal access token as parameters to az acr import. The following example imports a public image from the tensorflow repository in Docker Hub, using Docker Hub credentials:

az acr import \
  --name myregistry \
  --source docker.io/tensorflow/tensorflow:latest-gpu \
  --image tensorflow:latest-gpu \
  --username <Docker Hub user name> \
  --password <Docker Hub token>

Import container images from Microsoft Container Registry

For example, import the ltsc2022 Windows Server Core image from the windows repository in Microsoft Container Registry.

az acr import \
--name myregistry \
--source mcr.microsoft.com/windows/servercore:ltsc2022\
--image servercore:ltsc2022

Import container images from an Azure container registry in the same Microsoft Entra tenant

You can import an image from an Azure container registry in the same Microsoft Entra tenant by using integrated Microsoft Entra permissions.

  • Your identity must have permissions to view and pull images, tags, and OCI referrers from the source registry (Container Registry Data Importer and Data Reader role assigned on the source registry).

  • Your identity must also have permissions to both read images and trigger imports on the target registry (Container Registry Data Importer and Data Reader role assigned on the target registry).

  • The registry can be in the same or a different Azure subscription in the same Microsoft Entra tenant.

  • Public access to the source registry is disabled. If public access is disabled, specify the source registry by resource ID instead of by registry login server name.

  • The source registry and/or the target registry with a private endpoint or registry firewall rules must ensure the restricted registry allows trusted services to access the network.

Import container images from a registry in the same subscription

For example, import the aci-helloworld:latest image from a source registry mysourceregistry to myregistry in the same Azure subscription.

The following example imports the aci-helloworld:latest image to myregistry from a source registry mysourceregistry in which access to the registry's public endpoint is disabled. Supply the resource ID of the source registry with the --registry parameter. Notice that the --source parameter specifies only the source repository and tag, not the registry login server name.

To use Microsoft Entra identity authentication to the source registry, include the --registry <source-registry-resource-id> flag.

az acr import \
  --name myregistry \
  --source aci-helloworld:latest \
  --image aci-helloworld:latest \
  --registry /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sourceResourceGroup/providers/Microsoft.ContainerRegistry/registries/mysourceregistry

Import container images from a registry in a different subscription

Note

To import an image from one registry to another, the source and target registries must ensure that both regions are registered for Azure Container Registry (ACR) under the subscription’s resource providers.

In the following example, mysourceregistry is in a different subscription from myregistry in the same tenant. Supply the resource ID of the source registry by using the --registry parameter. The --source parameter specifies only the source repository and tag, not the registry login server name.

az acr import \
  --name myregistry \
  --source aci-helloworld:latest \
  --image aci-hello-world:latest \
  --registry /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sourceResourceGroup/providers/Microsoft.ContainerRegistry/registries/mysourceregistry

Import container images from a registry by using service principal credentials

To import from a registry that you can't access by using integrated Active Directory permissions, use service principal credentials (if available) for the source registry. Enter the appID and password of a Microsoft Entra service principal that has the correct role assignment access to the source registry.

  • For Microsoft Entra service principals, ensure either Container Registry Repository Reader (for ABAC-enabled registries) or AcrPull (for non-ABAC registries) is assigned.

Using a service principal is useful for build systems and other unattended systems that need to import images to your registry.

az acr import \
  --name myregistry \
  --source sourceregistry.azurecr.io/sourcerepo:tag \
  --image targetimage:tag \
  --username <SP_App_ID> \
  --password <SP_Passwd>

Import container images from an Azure container registry in a different tenant

To import images from an Azure container registry in a different Microsoft Entra tenant, specify the source registry by login server name, and provide credentials that enable pull access to the registry.

Cross-tenant import isn't supported over public access disabled registry.

Cross-tenant import with username and password

For example, use a non-Microsoft Entra repository-scoped token and password, or the appID and password of a Microsoft Entra service principal that has correct role assignments to the source registry.

  • For Microsoft Entra service principals, ensure either Container Registry Repository Reader (for ABAC-enabled registries) or AcrPull (for non-ABAC registries) is assigned on the source registry.
az acr import \
  --name myregistry \
  --source sourceregistry.azurecr.io/sourcerepo:tag \
  --image targetimage:tag \
  --username <SP_App_ID> \
  --password <SP_Passwd>

Cross-tenant import with access token

To access the source registry by using an identity in the source tenant that has registry permissions, get an access token:

# Login to Azure CLI with the identity, for example a user-assigned managed identity
az login --identity --username <identity_ID>

# Get access token returned by `az account get-access-token`
az account get-access-token

In the target tenant, pass the access token as a password to the az acr import command. The source registry specifies the login server name. No username is needed in this command:

az acr import \
  --name myregistry \
  --source sourceregistry.azurecr.io/sourcerepo:tag \
  --image targetimage:tag \
  --password ($token|ConvertFrom-Json).accessToken

Import container images from a non-Azure private container registry

Import an image from a non-Azure private registry by specifying credentials that enable pull access to the registry. For example, pull an image from a private Docker registry:

az acr import \
  --name myregistry \
  --source docker.io/sourcerepo/sourceimage:tag \
  --image sourceimage:tag \
  --username <username> \
  --password <password>

Troubleshoot problems with container image imports

If you see an error when importing an image, review the following table for more information.

Error message Explanation
The remote server may not be RFC 7233 compliant The distribution-spec allows range header form of Range: bytes=<start>-<end>. However, the remote server might not be RFC 7233 compliant.
Unexpected response status code An unexpected response status code was retrieved from the source repository when doing range query.
Unexpected length of body in response The received content length doesn't match the expected size. The expected size is decided by blob size and range header.

Next steps

In this article, you learned about importing container images to an Azure container registry from a public registry or another private registry.

  • Last updated on