Azure Container Registry Client Library

1.2.0 · active · verified Sat Apr 11

The Microsoft Azure Container Registry Client Library for Python provides an interface to interact with Azure Container Registry (ACR) services. It allows developers to manage container images, repositories, and other artifacts stored in ACR. The library is currently at version 1.2.0 and follows the Azure SDK for Python's regular release cadence, ensuring updates and feature parity with the service.

Warnings

gotcha Authentication with Azure Container Registry requires the `azure-identity` package and proper credential setup. `DefaultAzureCredential` is the recommended way, but relies on environment variables (e.g., `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`) or other configured Azure SDK authentication methods. Without correct setup, authentication will fail.
Fix: Ensure `pip install azure-identity` is run and that your environment variables are correctly configured for `DefaultAzureCredential`, or explicitly pass other credential types. Refer to Azure Identity documentation for detailed setup.
gotcha The authenticated identity (e.g., service principal, managed identity, user account) must have appropriate Azure RBAC roles assigned to the Container Registry. Common roles include `AcrPull` (read-only), `AcrPush` (read/write), or `Owner`/`Contributor` for full management. Insufficient permissions will result in authorization errors.
Fix: Verify that the Azure AD principal used for authentication has the necessary permissions granted on the Azure Container Registry resource in the Azure portal or via Azure CLI/PowerShell.
gotcha This library (`azure-containerregistry`) is the data-plane client for interacting with repositories, images, and manifests. It should not be confused with the management-plane client (`azure-mgmt-containerregistry`), which is used for creating, updating, and deleting the Container Registry *resource itself*.
Fix: If you intend to manage the ACR resource (e.g., create/delete registries, configure geo-replication), use `azure-mgmt-containerregistry`. If you need to push/pull images, list repositories, or manage manifests within an existing registry, use `azure-containerregistry`.

Install

pip install azure-containerregistry azure-identity Install core library and authentication

Imports

ContainerRegistryClient

from azure.containerregistry import ContainerRegistryClient

DefaultAzureCredential
```
from azure.identity import DefaultAzureCredential
```
Required for authentication using Azure Identity.

Quickstart

This quickstart demonstrates how to authenticate with Azure Container Registry using `DefaultAzureCredential` and then list all repository names within the specified registry. Ensure the `AZURE_CONTAINER_REGISTRY_URL` environment variable is set to your registry's URL (e.g., `https://myregistry.azurecr.io`) and that your authenticated identity has sufficient permissions (e.g., 'AcrPull' role).

import os
from azure.containerregistry import ContainerRegistryClient
from azure.identity import DefaultAzureCredential

# Set your ACR endpoint, e.g., 'https://myregistry.azurecr.io'
registry_url = os.environ.get('AZURE_CONTAINER_REGISTRY_URL', 'https://yourregistryname.azurecr.io')

# DefaultAzureCredential will try various authentication methods
# (environment variables, managed identity, VS Code, Azure CLI, etc.)
credential = DefaultAzureCredential()

client = ContainerRegistryClient(endpoint=registry_url, credential=credential)

try:
    print(f"Listing repositories in {registry_url}:")
    for repository_name in client.list_repository_names():
        print(f"- {repository_name}")
except Exception as e:
    print(f"An error occurred: {e}")
finally:
    client.close()
    credential.close()

view raw JSON →