Azure Storage Blob

12.28.0 verified Tue May 12 auth: no python install: verified quickstart: stale

Official Azure Blob Storage client library for Python. Current version: 12.28.0 (Mar 2026). v12 (released 2019) is a complete rewrite from v2.x — BlockBlobService removed, replaced by BlobServiceClient/ContainerClient/BlobClient. Most LLM training data and older tutorials use the removed v2 BlockBlobService API. Recommended auth is DefaultAzureCredential (azure-identity) not connection strings in production.

pip install azure-storage-blob

Common errors

error ImportError: cannot import name 'BlockBlobService' from 'azure.storage.blob' ↓

cause This error occurs because `BlockBlobService` was part of the older `azure-storage` (v2.x) library, which has been completely rewritten and replaced by `azure-storage-blob` (v12.x). The class `BlockBlobService` no longer exists in the v12 SDK.

fix

Migrate your code to use the new client classes: BlobServiceClient, ContainerClient, and BlobClient from azure.storage.blob. For example, instead of BlockBlobService, you would typically start with BlobServiceClient.from_connection_string() or authenticate with DefaultAzureCredential.

error ModuleNotFoundError: No module named 'azure.storage.blob.blockblobservice' ↓

cause This error indicates that the Python environment is attempting to import a module (`azure.storage.blob.blockblobservice`) that was part of the deprecated `azure-storage` (v2.x) SDK, but the currently installed library is the newer `azure-storage-blob` (v12.x) which restructured its modules.

fix

Uninstall any older azure-storage packages (pip uninstall azure-storage) and ensure azure-storage-blob is installed (pip install azure-storage-blob). Then, refactor your imports and code to use the v12 API (e.g., from azure.storage.blob import BlobServiceClient).

error AttributeError: 'BlobServiceClient' object has no attribute 'get_blob_to_bytes' ↓

cause This error arises when trying to call methods (like `get_blob_to_bytes`, `ls_files`, or `exists` directly on `BlobServiceClient`) that were available in older versions (v2.x) or on different client objects, but are not present on the `BlobServiceClient` in the `azure-storage-blob` (v12.x) library. Data operations are typically performed via `BlobClient` or `ContainerClient`.

fix

Obtain a BlobClient instance using blob_service_client.get_blob_client(container_name, blob_name) or container_client.get_blob_client(blob_name). Then, use the appropriate methods on the BlobClient (e.g., blob_client.download_blob().readall() to get bytes or blob_client.exists() to check existence).

error azure.core.exceptions.ClientAuthenticationError: Server failed to authenticate the request. ↓

cause This authentication error, often accompanied by messages like 'Make sure the value of Authorization header is formed correctly including the signature' or 'InvalidAuthenticationInfo', means the credentials provided (connection string, SAS token, or Azure AD token) are incorrect, expired, or lack the necessary permissions. System clock skew can also cause this.

fix

Verify your connection string or SAS token is correct and not expired. If using DefaultAzureCredential, ensure your local environment (Azure CLI login, VS Code login) or Azure hosting environment (Managed Identity, environment variables) is correctly configured and has the 'Storage Blob Data Contributor' RBAC role assigned to the storage account. Check system time for skew.

error ModuleNotFoundError: No module named 'azure.storage.blob' ↓

cause This is a fundamental error indicating that the `azure-storage-blob` package is either not installed in the current Python environment or the environment's `PYTHONPATH` is not correctly configured to locate it.

fix

Install the package using pip: pip install azure-storage-blob. If it's already installed, ensure you are running your script in the correct virtual environment, or that your system's PYTHONPATH includes the directory where packages are installed.

Warnings

breaking BlockBlobService removed in v12. Raises ImportError: 'cannot import name BlockBlobService'. This is the #1 error when using LLM-generated Azure storage code. ↓

fix from azure.storage.blob import BlobServiceClient — not BlockBlobService

breaking create_blob_from_path(), create_blob_from_text(), create_blob_from_stream(), get_blob_to_path(), get_blob_to_text() all removed in v12. Use upload_blob() and download_blob() instead. ↓

fix blob_client.upload_blob(data) and blob_client.download_blob().readall()

breaking SAS token generation moved from class method to standalone function in v12. Old: service.generate_account_shared_access_signature(). New: generate_account_sas() top-level function. ↓

fix from azure.storage.blob import generate_account_sas, ResourceTypes, AccountSasPermissions

gotcha upload_blob() raises ResourceExistsError if blob already exists. Default overwrite=False. Must pass overwrite=True to replace. ↓

fix blob_client.upload_blob(data, overwrite=True)

gotcha download_blob() returns a StorageStreamDownloader — not bytes directly. Must call .readall() or .read() to get content. ↓

fix content = blob_client.download_blob().readall()

gotcha DefaultAzureCredential is recommended for production but relies on multiple underlying authentication methods (e.g., environment variables, Azure CLI, Managed Identity). It will raise a ClientAuthenticationError if none of these methods are configured or accessible in the execution environment. ↓

fix Ensure one of DefaultAzureCredential's underlying authentication methods is properly configured for your environment. This might involve setting environment variables (e.g., AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET), logging in via the Azure CLI (`az login`), or ensuring a Managed Identity is assigned and accessible to the resource running the code. Also, ensure 'azure-identity' is installed.

gotcha Async client requires separate import: from azure.storage.blob.aio import BlobServiceClient. Mixing sync and async clients causes TypeError. ↓

fix from azure.storage.blob.aio import BlobServiceClient for async usage.

gotcha DefaultAzureCredential raises ClientAuthenticationError if it cannot find valid credentials in the execution environment. This often happens in non-Azure environments without Azure CLI logged in, or in Azure environments missing Managed Identity, environment variables (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET), or other configured credential sources. ↓

fix Ensure the execution environment has valid credentials configured for DefaultAzureCredential to discover. For local development, log in via Azure CLI (`az login`). For Azure deployments, use Managed Identity, set environment variables, or ensure a Workload Identity is properly configured. Install 'azure-identity-broker' for Visual Studio Code credential support.

Install

pip install azure-storage-blob azure-identity

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 1.09s 43.5M

3.10 alpine (musl) - - 1.08s 46.1M

3.10 slim (glibc) - - 0.77s 44M

3.10 slim (glibc) - - 0.77s 46M

3.11 alpine (musl) - - 1.37s 47.3M

3.11 alpine (musl) - - 1.36s 50.3M

3.11 slim (glibc) - - 1.11s 48M

3.11 slim (glibc) - - 1.14s 51M

3.12 alpine (musl) - - 1.57s 38.8M

3.12 alpine (musl) - - 1.49s 41.7M

3.12 slim (glibc) - - 1.45s 39M

3.12 slim (glibc) - - 1.47s 42M

3.13 alpine (musl) - - 1.51s 38.4M

3.13 alpine (musl) - - 1.51s 41.3M

3.13 slim (glibc) - - 1.43s 39M

3.13 slim (glibc) - - 1.44s 42M

3.9 alpine (musl) - - 1.05s 43.5M

3.9 alpine (musl) - - 1.04s 46.2M

3.9 slim (glibc) - - 0.92s 44M

3.9 slim (glibc) - - 0.95s 47M

Imports

BlobServiceClient (v12 — connection string)

wrong

from azure.storage.blob import BlockBlobService  # removed in v12
service = BlockBlobService(
    account_name='myaccount',
    account_key='mykey'
)
service.create_blob_from_path('mycontainer', 'myblob', 'file.txt')
service.get_blob_to_path('mycontainer', 'myblob', 'downloaded.txt')

correct

from azure.storage.blob import BlobServiceClient
import os

# From connection string
connect_str = os.environ['AZURE_STORAGE_CONNECTION_STRING']
blob_service_client = BlobServiceClient.from_connection_string(connect_str)

# Upload
container_client = blob_service_client.get_container_client('mycontainer')
with open('file.txt', 'rb') as data:
    container_client.upload_blob('myblob', data, overwrite=True)

# Download
blob_client = blob_service_client.get_blob_client(
    container='mycontainer', blob='myblob'
)
with open('downloaded.txt', 'wb') as f:
    f.write(blob_client.download_blob().readall())

BlockBlobService, create_blob_from_path, get_blob_to_path, get_blob_to_text all removed in v12. LLMs trained pre-2020 generate these patterns. Use BlobServiceClient + upload_blob/download_blob.

DefaultAzureCredential (recommended for production)

wrong

# Using connection string with account key in production — security risk
connect_str = 'DefaultEndpointsProtocol=https;AccountName=x;AccountKey=SECRET...'
blob_service_client = BlobServiceClient.from_connection_string(connect_str)

correct

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

# Passwordless auth — works locally (CLI/VS Code) and in Azure (managed identity)
credential = DefaultAzureCredential()
blob_service_client = BlobServiceClient(
    account_url='https://myaccount.blob.core.windows.net',
    credential=credential
)

# Upload
blob_client = blob_service_client.get_blob_client(
    container='mycontainer', blob='myblob'
)
with open('file.txt', 'rb') as data:
    blob_client.upload_blob(data, overwrite=True)

Connection strings expose account keys. Use DefaultAzureCredential + managed identity in production. Connection strings are acceptable for local dev only.

Quickstart stale last tested: 2026-04-23

azure-storage-blob v12 with DefaultAzureCredential upload/download.

# pip install azure-storage-blob azure-identity
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

# Production: passwordless auth
credential = DefaultAzureCredential()
blob_service_client = BlobServiceClient(
    account_url='https://myaccount.blob.core.windows.net',
    credential=credential
)

# Create container
container_client = blob_service_client.create_container('mycontainer')

# Upload from file
blob_client = blob_service_client.get_blob_client(
    container='mycontainer', blob='sample.txt'
)
with open('sample.txt', 'rb') as data:
    blob_client.upload_blob(data)

# List blobs
for blob in blob_service_client.get_container_client('mycontainer').list_blobs():
    print(blob.name)

# Download
downloader = blob_client.download_blob()
content = downloader.readall()
print(content)