Quickstart: Create a private container registry using Azure PowerShell

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 Azure PowerShell. Then, use Docker commands to push a container image into the registry, and finally pull and run the image from your registry.



We recommend that you use the Azure Az PowerShell module to interact with Azure. To get started, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

This quickstart requires Azure PowerShell module. Run Get-Module -ListAvailable Az to determine your installed version. If you need to install or upgrade, see Install Azure PowerShell module.

You must also have Docker installed locally. Docker provides packages for macOS, Windows, and Linux systems.

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.

Sign in to Azure

Sign in to your Azure subscription with the Connect-AzAccount command, and follow the on-screen directions.


Create resource group

Once you're authenticated with Azure, create a resource group with New-AzResourceGroup. A resource group is a logical container in which you deploy and manage your Azure resources.

New-AzResourceGroup -Name myResourceGroup -Location EastUS

Create container registry

Next, create a container registry in your new resource group with the New-AzContainerRegistry command.

The registry name must be unique within Azure, and contain 5-50 alphanumeric characters. The following example creates a registry named "mycontainerregistry." Replace mycontainerregistry in the following command, then run it to create the registry:

$registry = New-AzContainerRegistry -ResourceGroupName "myResourceGroup" -Name "mycontainerregistry" -EnableAdminUser -Sku Basic


In this quickstart, you create a Basic registry, which is a cost-optimized option for developers learning about Azure Container Registry. Choose other tiers for increased storage and image throughput, and capabilities such as connection using a private endpoint. For details on available service tiers (SKUs), see Container registry service tiers.

Log in to registry

Before pushing and pulling container images, you must log in to your registry with the Connect-AzContainerRegistry cmdlet. The following example uses the same credentials you logged in with when authenticating to Azure with the Connect-AzAccount cmdlet.


In the following example, the value of $registry.Name is the resource name, not the fully qualified registry name.

Connect-AzContainerRegistry -Name $registry.Name

The command returns Login Succeeded 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 with the fully qualified name of your registry login server. The login server name is in the format <registry-name>.azurecr.io (must be all lowercase), for example, mycontainerregistry.azurecr.io.

Tag the image using the docker tag command. Replace <login-server> with the login server name of your ACR instance.

docker tag mcr.microsoft.com/hello-world <login-server>/hello-world:v1


docker tag mcr.microsoft.com/hello-world mycontainerregistry.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 does not remove the image from the hello-world repository in your Azure container registry.)

docker rmi <login-server>/hello-world: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

Once you're done working with the resources you created in this quickstart, use the Remove-AzResourceGroup command to remove the resource group, the container registry, and the container images stored there:

Remove-AzResourceGroup -Name myResourceGroup

Next steps

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