{"id":174,"library":"azure-storage-blob","title":"Azure Storage Blob","description":"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.","status":"active","version":"12.28.0","language":"python","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-blob","tags":["azure","blob-storage","cloud","python","storage","azure-sdk"],"install":[{"cmd":"pip install azure-storage-blob","lang":"bash","label":"Python (blob storage)"},{"cmd":"pip install azure-storage-blob azure-identity","lang":"bash","label":"Python (with DefaultAzureCredential — recommended)"}],"dependencies":[{"reason":"Required. Installed automatically.","package":"azure-core","optional":false},{"reason":"Required for DefaultAzureCredential / managed identity auth. Recommended for production.","package":"azure-identity","optional":true}],"imports":[{"note":"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.","wrong":"from azure.storage.blob import BlockBlobService  # removed in v12\nservice = BlockBlobService(\n    account_name='myaccount',\n    account_key='mykey'\n)\nservice.create_blob_from_path('mycontainer', 'myblob', 'file.txt')\nservice.get_blob_to_path('mycontainer', 'myblob', 'downloaded.txt')","symbol":"BlobServiceClient (v12 — connection string)","correct":"from azure.storage.blob import BlobServiceClient\nimport os\n\n# From connection string\nconnect_str = os.environ['AZURE_STORAGE_CONNECTION_STRING']\nblob_service_client = BlobServiceClient.from_connection_string(connect_str)\n\n# Upload\ncontainer_client = blob_service_client.get_container_client('mycontainer')\nwith open('file.txt', 'rb') as data:\n    container_client.upload_blob('myblob', data, overwrite=True)\n\n# Download\nblob_client = blob_service_client.get_blob_client(\n    container='mycontainer', blob='myblob'\n)\nwith open('downloaded.txt', 'wb') as f:\n    f.write(blob_client.download_blob().readall())"},{"note":"Connection strings expose account keys. Use DefaultAzureCredential + managed identity in production. Connection strings are acceptable for local dev only.","wrong":"# Using connection string with account key in production — security risk\nconnect_str = 'DefaultEndpointsProtocol=https;AccountName=x;AccountKey=SECRET...'\nblob_service_client = BlobServiceClient.from_connection_string(connect_str)","symbol":"DefaultAzureCredential (recommended for production)","correct":"from azure.identity import DefaultAzureCredential\nfrom azure.storage.blob import BlobServiceClient\n\n# Passwordless auth — works locally (CLI/VS Code) and in Azure (managed identity)\ncredential = DefaultAzureCredential()\nblob_service_client = BlobServiceClient(\n    account_url='https://myaccount.blob.core.windows.net',\n    credential=credential\n)\n\n# Upload\nblob_client = blob_service_client.get_blob_client(\n    container='mycontainer', blob='myblob'\n)\nwith open('file.txt', 'rb') as data:\n    blob_client.upload_blob(data, overwrite=True)\n"}],"quickstart":{"code":"# pip install azure-storage-blob azure-identity\nfrom azure.identity import DefaultAzureCredential\nfrom azure.storage.blob import BlobServiceClient\n\n# Production: passwordless auth\ncredential = DefaultAzureCredential()\nblob_service_client = BlobServiceClient(\n    account_url='https://myaccount.blob.core.windows.net',\n    credential=credential\n)\n\n# Create container\ncontainer_client = blob_service_client.create_container('mycontainer')\n\n# Upload from file\nblob_client = blob_service_client.get_blob_client(\n    container='mycontainer', blob='sample.txt'\n)\nwith open('sample.txt', 'rb') as data:\n    blob_client.upload_blob(data)\n\n# List blobs\nfor blob in blob_service_client.get_container_client('mycontainer').list_blobs():\n    print(blob.name)\n\n# Download\ndownloader = blob_client.download_blob()\ncontent = downloader.readall()\nprint(content)","lang":"python","description":"azure-storage-blob v12 with DefaultAzureCredential upload/download."},"warnings":[{"fix":"from azure.storage.blob import BlobServiceClient — not BlockBlobService","message":"BlockBlobService removed in v12. Raises ImportError: 'cannot import name BlockBlobService'. This is the #1 error when using LLM-generated Azure storage code.","severity":"breaking","affected_versions":">= 12.0"},{"fix":"blob_client.upload_blob(data) and blob_client.download_blob().readall()","message":"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.","severity":"breaking","affected_versions":">= 12.0"},{"fix":"from azure.storage.blob import generate_account_sas, ResourceTypes, AccountSasPermissions","message":"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.","severity":"breaking","affected_versions":">= 12.0"},{"fix":"blob_client.upload_blob(data, overwrite=True)","message":"upload_blob() raises ResourceExistsError if blob already exists. Default overwrite=False. Must pass overwrite=True to replace.","severity":"gotcha","affected_versions":"all"},{"fix":"content = blob_client.download_blob().readall()","message":"download_blob() returns a StorageStreamDownloader — not bytes directly. Must call .readall() or .read() to get content.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"from azure.storage.blob.aio import BlobServiceClient for async usage.","message":"Async client requires separate import: from azure.storage.blob.aio import BlobServiceClient. Mixing sync and async clients causes TypeError.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T09:37:21.854Z","next_check":"2026-06-25T00:00:00.000Z","problems":[{"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`.","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.","error":"ImportError: cannot import name 'BlockBlobService' from 'azure.storage.blob'"},{"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`).","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.","error":"ModuleNotFoundError: No module named 'azure.storage.blob.blockblobservice'"},{"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).","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`.","error":"AttributeError: 'BlobServiceClient' object has no attribute 'get_blob_to_bytes'"},{"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.","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.","error":"azure.core.exceptions.ClientAuthenticationError: Server failed to authenticate the request."},{"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.","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.","error":"ModuleNotFoundError: No module named 'azure.storage.blob'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.09,"mem_mb":17.6,"disk_size":"43.5M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.08,"mem_mb":17.6,"disk_size":"46.1M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.77,"mem_mb":17.6,"disk_size":"44M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.77,"mem_mb":17.6,"disk_size":"46M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.37,"mem_mb":20.3,"disk_size":"47.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.36,"mem_mb":20.3,"disk_size":"50.3M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.11,"mem_mb":20.3,"disk_size":"48M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.14,"mem_mb":20.3,"disk_size":"51M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.57,"mem_mb":20.1,"disk_size":"38.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.49,"mem_mb":20.1,"disk_size":"41.7M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.45,"mem_mb":20.1,"disk_size":"39M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.47,"mem_mb":20.1,"disk_size":"42M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.51,"mem_mb":21,"disk_size":"38.4M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.51,"mem_mb":21,"disk_size":"41.3M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.43,"mem_mb":21,"disk_size":"39M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.44,"mem_mb":21,"disk_size":"42M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.05,"mem_mb":17.6,"disk_size":"43.5M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.04,"mem_mb":17.6,"disk_size":"46.2M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.92,"mem_mb":17.6,"disk_size":"44M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.95,"mem_mb":17.6,"disk_size":"47M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}