Create a private Docker container registry using the Azure CLI 2.0

Use commands in the Azure CLI 2.0 to create a container registry and manage its settings from your Linux, Mac, or Windows computer. You can also create and manage container registries using the Azure portal or programmatically with the Container Registry REST API.

  • For background and concepts, see the overview
  • For help on Container Registry CLI commands (az acr commands), pass the -h parameter to any command.


  • Azure CLI 2.0: To install and get started with the CLI 2.0, see the installation instructions. Log in to your Azure subscription by running az login. For more information, see Get started with the CLI 2.0.
  • Resource group: Create a resource group before creating a container registry, or use an existing resource group. Make sure the resource group is in a location where the Container Registry service is available. To create a resource group using the CLI 2.0, see the CLI 2.0 reference.
  • Storage account (optional): Create a standard Azure storage account to back the container registry in the same location. If you don't specify a storage account when creating a registry with az acr create, the command creates one for you. To create a storage account using the CLI 2.0, see the CLI 2.0 reference. Currently Premium Storage is not supported.
  • Service principal (optional): When you create a registry with the CLI, by default it is not set up for access. Depending on your needs, you can assign an existing Azure Active Directory service principal to a registry (or create and assign a new one), or enable the registry's admin user account. See the sections later in this article. For more information about registry access, see Authenticate with the container registry.

Create a container registry

Run the az acr create command to create a container registry.


When you create a registry, specify a globally unique top-level domain name, containing only letters and numbers. The registry name in the examples is myRegistry1, but substitute a unique name of your own.

The following command uses the minimal parameters to create container registry myRegistry1 in the resource group myResourceGroup, and using the Basic sku:

az acr create --name myRegistry1 --resource-group myResourceGroup --sku Basic
  • --storage-account-name is optional. If not specified, a storage account is created with a name consisting of the registry name and a timestamp in the specified resource group.

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

  "adminUserEnabled": false,
  "creationDate": "2017-06-06T18:36:29.124842+00:00",
  "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myResourceGroup/providers/Microsoft.ContainerRegistry
  "location": "southcentralus",
  "loginServer": "",
  "name": "myRegistry1",
  "provisioningState": "Succeeded",
  "sku": {
    "name": "Basic",
    "tier": "Basic"
  "storageAccount": {
    "name": "myregistry123456789"
  "tags": {},
  "type": "Microsoft.ContainerRegistry/registries"

Take special note:

  • id - Identifier for the registry in your subscription, which you need if you want to assign a service principal.
  • loginServer - The fully qualified name you specify to log in to the registry. In this example, the name is (all lowercase).

Assign a service principal

Use CLI 2.0 commands to assign an Azure Active Directory service principal to a registry. The service principal in these examples is assigned the Owner role, but you can assign other roles if you want.

Create a service principal and assign access to the registry

In the following command, a new service principal is assigned Owner role access to the registry identifier passed with the --scopes parameter. Specify a strong password with the --password parameter.

az ad sp create-for-rbac --scopes /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myresourcegroup/providers/Microsoft.ContainerRegistry/registries/myregistry1 --role Owner --password myPassword

Assign an existing service principal

If you already have a service principal and want to assign it Owner role access to the registry, run a command similar to the following example. You pass the service principal app ID using the --assignee parameter:

az role assignment create --scope /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myresourcegroup/providers/Microsoft.ContainerRegistry/registries/myregistry1 --role Owner --assignee myAppId

Manage admin credentials

An admin account is automatically created for each container registry and is disabled by default. The following examples show az acr CLI commands to manage the admin credentials for your container registry.

Obtain admin user credentials

az acr credential show -n myRegistry1

Enable admin user for an existing registry

az acr update -n myRegistry1 --admin-enabled true

Disable admin user for an existing registry

az acr update -n myRegistry1 --admin-enabled false

List images and tags

Use the az acr CLI commands to query the images and tags in a repository.


Currently, Container Registry does not support the docker search command to query for images and tags.

List repositories

The following example lists the repositories in a registry, in JSON (JavaScript Object Notation) format:

az acr repository list -n myRegistry1 -o json

List tags

The following example lists the tags on the samples/nginx repository, in JSON format:

az acr repository show-tags -n myRegistry1 --repository samples/nginx -o json

Next steps