The `azure-batch` client library for Python enables users to configure compute nodes and pools, define tasks, and manage jobs for large-scale parallel and high-performance computing (HPC) applications in Azure. The current stable version is 14.2.0, with ongoing development as part of the broader Azure SDK for Python, which typically sees monthly releases for various packages.
Install & Compatibility
Where this runs
tested against v15.1.0b3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
9/10 runs
9/10 runs
py 3.11
9/10 runs
9/10 runs
py 3.12
9/10 runs
9/10 runs
py 3.13
9/10 runs
9/10 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BatchServiceClient
✓ from azure.batch import BatchServiceClient
✗ from azure.batch.batch_service_client import BatchServiceClient
Direct import from the top-level package is standard.
models
✓ from azure.batch import models
✗ from azure.batch.models import ...
Models are typically exposed directly under the `azure.batch` namespace for convenience.
DefaultAzureCredential
✓ from azure.identity import DefaultAzureCredential
The standard credential type for authenticating with Azure services using Microsoft Entra ID.
SharedKeyCredentials
✓ from azure.batch.batch_auth import SharedKeyCredentials
Used for shared key authentication, though Microsoft Entra ID is now recommended.
This quickstart demonstrates how to instantiate `BatchServiceClient` using the recommended `DefaultAzureCredential` from `azure-identity`. It retrieves the Batch account URL from an environment variable and then lists the existing pools. For shared key authentication, an alternative commented-out section is provided.
import os
from azure.batch import BatchServiceClient
from azure.identity import DefaultAzureCredential
# Retrieve Batch account details from environment variables
batch_account_url = os.environ.get("AZURE_BATCH_ACCOUNT_URL", "https://<your-batch-account>.westus.batch.azure.com")
# Authenticate using DefaultAzureCredential (recommended for Azure AD)
# This will attempt to authenticate via environment variables, managed identity, etc.
try:
credential = DefaultAzureCredential()
batch_client = BatchServiceClient(credential, batch_url=batch_account_url)
# Example: List existing pools
pools = batch_client.pool.list()
print(f"Successfully connected to Azure Batch. Found {len(pools)} pools.")
for pool in pools:
print(f" - Pool ID: {pool.id}, VM Size: {pool.vm_size}")
except Exception as e:
print(f"Error connecting to Azure Batch: {e}")
print("Please ensure AZURE_BATCH_ACCOUNT_URL is set and your environment is authenticated (e.g., via Azure CLI).")
# For shared key authentication (less recommended, but available):
# batch_account_name = os.environ.get("AZURE_BATCH_ACCOUNT_NAME", "<your-batch-account-name>")
# batch_account_key = os.environ.get("AZURE_BATCH_ACCOUNT_KEY", "<your-batch-account-key>")
# if batch_account_name and batch_account_key:
# from azure.batch.batch_auth import SharedKeyCredentials
# creds = SharedKeyCredentials(batch_account_name, batch_account_key)
# batch_client_shared_key = BatchServiceClient(creds, batch_url=batch_account_url)
# print("Successfully connected with Shared Key credentials.")
Debug
Known issues
breakingVersion 15.x and above introduces significant changes and improvements from v14.x and below. A migration guide is available in the official GitHub repository's README.fixConsult the official migration guide for `azure-batch` in the Azure SDK for Python GitHub repository to adapt your code. This often involves changes to client instantiation and model usage.
affects: >=15.0.0
breakingThe `lifetime statistics API` was removed in version 14.0.0. Specifically, `job.get_all_lifetime_statistics` and `pool.get_all_lifetime_statistics` are no longer supported.fixRemove calls to `get_all_lifetime_statistics` methods. You may need to implement custom logic to track lifetime statistics if needed, using other available APIs.
affects: >=14.0.0
deprecatedCertificateOperations-related methods were deprecated in version 14.0.0 and were scheduled for removal after February 2024. Users are advised to use Azure KeyVault Extension instead.fixMigrate any certificate management logic to use Azure KeyVault Extension. Avoid using the deprecated CertificateOperations methods.
affects: >=14.0.0
gotchaMicrosoft Entra ID (formerly Azure AD) authentication using `azure-identity` and `DefaultAzureCredential` is strongly recommended for `azure-batch`. Some Batch capabilities require this, and Batch account API authentication can be restricted to only Microsoft Entra ID, rejecting shared key authentication.fixAlways prefer `DefaultAzureCredential` from `azure-identity` for authentication. Ensure your application or user principal has appropriate Azure RBAC roles assigned to the Batch account.
affects: All
gotchaWhen installing packages on Batch compute nodes, if using StartTask, ensure the Python environment is correctly set up. Common issues include `pip` not being recognized or incorrect Python versions.fixUse a platform image that comes with a suitable Python environment (e.g., Ubuntu 18.04 LTS for Python 3.6). If custom packages are needed, use a `StartTask` to install them (e.g., `pip install -r requirements.txt`) or consider custom VM images. Ensure correct paths for Python executables.
affects: All
gotchaThe default task retention time for all tasks was changed from infinite to 7 days. This means task-related files and stdout/stderr logs will only be available for 7 days by default.fixIf longer retention is required, explicitly set the `retention_time` property when creating tasks or jobs. Ensure critical output files are persisted to an Azure Storage account.
affects: <=14.x (changed in an older version, but still a common pitfall)
Audit
Dependencies
azure-identityrequiredRecommended for modern Azure Active Directory (Entra ID) authentication.
azure-storage-bloboptionalOften used in conjunction with Azure Batch for input/output data storage.