Quickstart: Create a private container registry using the Azure CLI

Azure Container Registry is a private registry service for building, storing, and managing container images and related artifacts. In this quickstart, you create an Azure container registry instance with the Azure CLI. Then, use Docker commands to push a container image into the registry, and finally pull and run the image from your registry.

This quickstart requires that you are running the Azure CLI (version 2.0.55 or later recommended). Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.

You must also have Docker installed locally. Docker provides packages that easily configure Docker on any macOS, Windows, or Linux system.

Because the Azure Cloud Shell doesn't include all required Docker components (the dockerd daemon), you can't use the Cloud Shell for this quickstart.

Create a resource group

Create a resource group with the az group create command. An Azure resource group is a logical container into which Azure resources are deployed and managed.

The following example creates a resource group named myResourceGroup in the eastus location.

az group create --name myResourceGroup --location eastus

Configure parameters for a container registry

In this quickstart you create a Standard registry, which is sufficient for most Azure Container Registry workflows. For details on available service tiers, see Container registry service tiers.

Create an ACR instance using the az acr create command. The registry name must be unique within Azure, and contain 5-50 lowercase alphanumeric characters. In the following example, mycontainerregistry is used. Update this to a unique value.

Configure role assignment permissions mode

You can optionally use the --role-assignment-mode parameter to specify the role assignment mode of the registry. This option determines how Microsoft Entra role-based access control (RBAC) and role assignments are managed for the registry, including the use of Microsoft Entra attribute-based access control (ABAC) for Microsoft Entra repository permissions.

Specify rbac-abac for this parameter to retain standard Microsoft Entra RBAC role assignments, while optionally applying Microsoft Entra ABAC conditions for fine‑grained, repository‑level access control.

For more information on this option, see Microsoft Entra attribute-based access control (ABAC) for repository permissions.

Create a container registry

az acr create --resource-group myResourceGroup \
  --name mycontainerregistry --sku Standard \
  --role-assignment-mode 'rbac-abac'

When the registry is created, the output is similar to the following:

{
  "adminUserEnabled": false,
  "creationDate": "2019-01-08T22:32:13.175925+00:00",
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myResourceGroup/providers/Microsoft.ContainerRegistry/registries/mycontainerregistry",
  "location": "eastus",
  "loginServer": "mycontainerregistry.azurecr.io",
  "name": "mycontainerregistry",
  "provisioningState": "Succeeded",
  "resourceGroup": "myResourceGroup",
  "sku": {
    "name": "Standard",
    "tier": "Standard"
  },
  "status": null,
  "storageAccount": null,
  "tags": {},
  "type": "Microsoft.ContainerRegistry/registries"
}

Take note of loginServer in the output, which is the fully qualified registry name (all lowercase). Throughout the rest of this quickstart <registry-name> is a placeholder for the container registry name, and <login-server> is a placeholder for the registry's login server name.

Log in to registry

Before pushing and pulling container images, you must log in to the registry. To do so, use the az acr login command. Specify only the registry resource name when logging in with the Azure CLI. Don't use the fully qualified login server name.

az acr login --name <registry-name>

Example:

az acr login --name mycontainerregistry

The command returns a Login Succeeded message once completed.

Push image to registry

To push an image to an Azure Container registry, you must first have an image. If you don't yet have any local container images, run the following docker pull command to pull an existing public image. For this example, pull the hello-world image from Microsoft Container Registry.

docker pull mcr.microsoft.com/hello-world

Before you can push an image to your registry, you must tag it using the docker tag with the fully qualified name of your registry login server.

• The login server name format for Domain Name Label (DNL) protected registries with a unique DNS name hash included is mycontainerregistry-abc123.azurecr.io.
• The login server name format for registries created with the Unsecure DNL option is mycontainerregistry.azurecr.io.

For example, if your registry was created with the Tenant Reuse DNL scope, the login server might look like mycontainerregistry-abc123.azurecr.io with a hash in the DNS name. If your registry was created with the Unsecure DNL option, the login server would look like mycontainerregistry.azurecr.io without the hash.

For more details on DNL options during registry creation and DNS name implications, see Quickstart - Create Registry in Portal.

Example: Tagging an image before push

Tag the image using the docker tag command using your registry's login server.

Tagging image for a non-DNL registry:

docker tag mcr.microsoft.com/hello-world mycontainerregistry.azurecr.io/hello-world:v1

Tagging image for a DNL-enabled registry:

docker tag mcr.microsoft.com/hello-world mycontainerregistry-abc123.azurecr.io/hello-world:v1

Finally, use docker push to push the image to the registry instance. Replace <login-server> with the login server name of your registry instance. This example creates the hello-world repository, containing the hello-world:v1 image.

docker push <login-server>/hello-world:v1

After pushing the image to your container registry, remove the hello-world:v1 image from your local Docker environment. (Note that this docker rmi command doesn't remove the image from the hello-world repository in your Azure container registry.)

docker rmi <login-server>/hello-world:v1

List container images

The following example lists the repositories in your registry:

az acr repository list --name <registry-name> --output table

Output:

Result
----------------
hello-world

The following example lists the tags on the hello-world repository.

az acr repository show-tags --name <registry-name> --repository hello-world --output table

Output:

Result
--------
v1

Run image from registry

Now, you can pull and run the hello-world:v1 container image from your container registry by using docker run:

docker run <login-server>/hello-world:v1  

Example output:

Unable to find image 'mycontainerregistry.azurecr.io/hello-world:v1' locally
v1: Pulling from hello-world
Digest: sha256:662dd8e65ef7ccf13f417962c2f77567d3b132f12c95909de6c85ac3c326a345
Status: Downloaded newer image for mycontainerregistry.azurecr.io/hello-world:v1

Hello from Docker!
This message shows that your installation appears to be working correctly.

[...]

Clean up resources

When no longer needed, you can use the az group delete command to remove the resource group, the container registry, and the container images stored there.

az group delete --name myResourceGroup

Next steps

In this quickstart, you created an Azure Container Registry with the Azure CLI, pushed a container image to the registry, and pulled and ran the image from the registry. Continue to the Azure Container Registry tutorials for a deeper look at ACR.