{"id":613,"library":"azure-storage-queue","title":"Azure Queue Storage Client Library for Python","description":"The Azure Queue Storage client library for Python (azure-storage-queue) enables Python applications to interact with Azure Queue Storage, a service for storing large numbers of messages. A single queue message can be up to 64 KB in size, and a queue can contain millions of messages, facilitating asynchronous work backlogs and decoupled distributed applications. The library is actively maintained as part of the Azure SDK for Python, with version 12.15.0 being the latest stable release.","status":"active","version":"12.15.0","language":"python","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-queue","tags":["azure","storage","queue","cloud","messaging","sdk"],"install":[{"cmd":"pip install azure-storage-queue azure-identity","lang":"bash","label":"Install with Azure Identity"}],"dependencies":[{"reason":"Recommended for passwordless authentication to Azure services, which is the preferred and more secure authentication method for production environments.","package":"azure-identity","optional":false}],"imports":[{"note":"Old SDK versions might have used different class names or module structures. Always use the specific 'QueueServiceClient' for clarity and compatibility with the current SDK.","wrong":"from azure.storage.queue import ServiceClient","symbol":"QueueServiceClient","correct":"from azure.storage.queue import QueueServiceClient"},{"symbol":"QueueClient","correct":"from azure.storage.queue import QueueClient"},{"note":"The `azure-identity` library with `DefaultAzureCredential` is the recommended modern approach for authentication, replacing older credential types and patterns in `azure.common`.","wrong":"from azure.common.credentials import ServicePrincipalCredentials","symbol":"DefaultAzureCredential","correct":"from azure.identity import DefaultAzureCredential"},{"symbol":"BinaryBase64EncodePolicy","correct":"from azure.storage.queue import BinaryBase64EncodePolicy"},{"symbol":"BinaryBase64DecodePolicy","correct":"from azure.storage.queue import BinaryBase64DecodePolicy"}],"quickstart":{"code":"import os, uuid\nfrom azure.identity import DefaultAzureCredential\nfrom azure.storage.queue import QueueServiceClient, QueueClient, BinaryBase64EncodePolicy, BinaryBase64DecodePolicy\n\ntry:\n    print('Azure Queue storage - Python quickstart sample')\n\n    # Retrieve the connection string for use with the application.\n    # The storage connection string is a key for accessing your storage account.\n    # It is recommended to use passwordless authentication in production.\n    connect_str = os.environ.get('AZURE_STORAGE_CONNECTION_STRING', '')\n    queue_name = \"quickstart-\" + str(uuid.uuid4())\n\n    # Create the QueueServiceClient object\n    if connect_str:\n        # Authenticate with connection string\n        queue_service_client = QueueServiceClient.from_connection_string(\n            connect_str, \n            message_encode_policy=BinaryBase64EncodePolicy(),\n            message_decode_policy=BinaryBase64DecodePolicy()\n        )\n        print(\"Using connection string for authentication.\")\n    else:\n        # Authenticate with DefaultAzureCredential\n        account_url = os.environ.get('AZURE_STORAGE_ACCOUNT_URL') # e.g., 'https://<account-name>.queue.core.windows.net'\n        if not account_url:\n            raise ValueError(\"Please set AZURE_STORAGE_CONNECTION_STRING or AZURE_STORAGE_ACCOUNT_URL environment variable.\")\n\n        credential = DefaultAzureCredential()\n        queue_service_client = QueueServiceClient(\n            account_url=account_url, \n            credential=credential,\n            message_encode_policy=BinaryBase64EncodePolicy(),\n            message_decode_policy=BinaryBase64DecodePolicy()\n        )\n        print(\"Using DefaultAzureCredential for authentication.\")\n\n    # Get a client to interact with the queue\n    queue_client = queue_service_client.get_queue_client(queue_name)\n\n    # Create a queue\n    print(f\"Creating queue: {queue_name}\")\n    queue_client.create_queue()\n\n    # Send a message\n    message1 = \"Hello, Azure Queue!\"\n    print(f\"Adding message: {message1}\")\n    queue_client.send_message(message1)\n\n    message2 = \"This is a second message.\"\n    print(f\"Adding message: {message2}\")\n    queue_client.send_message(message2)\n\n    # Peek at messages\n    print(\"Peeking at messages...\")\n    peeked_messages = queue_client.peek_messages(max_messages=5)\n    for peeked_message in peeked_messages:\n        print(f\"Peeked message: {peeked_message.content}\")\n\n    # Receive and delete messages\n    print(\"Receiving and deleting messages...\")\n    messages = queue_client.receive_messages(messages_per_page=1)\n    for message in messages:\n        print(f\"Received message: {message.content}\")\n        queue_client.delete_message(message)\n        print(f\"Deleted message: {message.content}\")\n\n    print(f\"Successfully completed the quickstart. Deleting queue: {queue_name}\")\n    queue_client.delete_queue()\n\nexcept Exception as ex:\n    print(f\"Exception: {ex}\")\n","lang":"python","description":"This quickstart demonstrates how to create a `QueueServiceClient` (using either a connection string or `DefaultAzureCredential`), create a queue, send messages, peek at messages, receive and delete messages, and finally delete the queue. It highlights the use of `BinaryBase64EncodePolicy` and `BinaryBase64DecodePolicy` for message handling. Ensure `AZURE_STORAGE_CONNECTION_STRING` or `AZURE_STORAGE_ACCOUNT_URL` and necessary Azure Identity environment variables (e.g., `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`) are set for authentication."},"warnings":[{"fix":"Rewrite client initialization and interactions using the `azure-storage-queue` library. Prioritize passwordless authentication with `DefaultAzureCredential` over shared keys. Refer to the official migration guides.","message":"Major architectural changes occurred with the release of the v12 SDK. Older client libraries (e.g., `azure-storage` or `Microsoft.Azure.Storage.Queue`) are deprecated and no longer maintained. Applications must migrate to the `azure-storage-queue` package, which involves new client constructors, model names, and authentication patterns.","severity":"breaking","affected_versions":"All versions prior to 12.0.0"},{"fix":"Always use `BinaryBase64EncodePolicy()` and `BinaryBase64DecodePolicy()` when creating `QueueServiceClient` or `QueueClient` if you intend to send/receive non-string data that requires base64 encoding/decoding. For JSON messages, ensure you explicitly `json.dumps()` before sending and `json.loads()` after decoding.","message":"Messages sent to and received from Azure Queue Storage are often base64 encoded by default, especially when dealing with non-string content like JSON or binary data. Failing to explicitly encode before sending or decode after receiving can lead to corrupted data or deserialization errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement custom dead-lettering logic by tracking retry counts. If a message exceeds a configured retry threshold, move it to a separate 'poison message' queue or log it for manual inspection and removal from the main queue.","message":"Azure Queue Storage lacks a built-in dead-letter queue mechanism, unlike Azure Service Bus. If a message consistently fails processing, it will reappear in the queue after its visibility timeout expires. This can lead to a 'poison message' blocking workers indefinitely and requiring manual intervention.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Migrate to passwordless authentication using Azure Identity. Leverage `DefaultAzureCredential` with Managed Identities for Azure-hosted applications or environment variables for local development. Ensure appropriate Azure RBAC roles (e.g., 'Storage Queue Data Contributor') are assigned.","message":"Using shared access keys or connection strings directly in application code is discouraged, especially in production. This poses a security risk and complicates key rotation.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Adjust the `visibility_timeout` parameter when receiving messages to allow sufficient time for processing. If processing takes longer than expected, extend the visibility timeout using `update_message`. Ensure messages are deleted after successful processing.","message":"Incorrectly managing message visibility timeouts can lead to messages reappearing in the queue before processing is complete (leading to reprocessing) or being lost if the application crashes and the message is not explicitly deleted within the timeout.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that the necessary environment variables (`AZURE_STORAGE_CONNECTION_STRING` or `AZURE_STORAGE_ACCOUNT_URL`, or relevant Azure Identity variables like `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET` for `DefaultAzureCredential`) are correctly set in the application's environment before client initialization. For production, consider using Managed Identities with `DefaultAzureCredential` for enhanced security.","message":"The application failed to connect to Azure Queue Storage because no authentication details were provided. A connection string (`AZURE_STORAGE_CONNECTION_STRING`), an account URL (`AZURE_STORAGE_ACCOUNT_URL`), or Azure Identity credentials (e.g., via `DefaultAzureCredential` and related environment variables) are required to establish a connection.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T16:42:22.594Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Verify that the storage account name and account key are correct and up-to-date. If using a SAS token, ensure it is valid, has the necessary permissions (read, write, etc.), and has not expired. Also, check that your system's clock is synchronized, as a significant time difference can cause authentication failures.","cause":"This error typically indicates an issue with the credentials used to access the Azure Queue Storage, such as an incorrect account name, account key, Shared Access Signature (SAS) token, or an expired SAS token.","error":"Server failed to authenticate the request. Make sure the value of Authorization header is formed correctly including the signature."},{"fix":"First, uninstall any old `azure-storage` packages: `pip uninstall azure-storage`. Then, ensure you have the correct, service-specific client library installed: `pip install azure-storage-queue`. Update your import statements to `from azure.storage.queue import QueueServiceClient` or `QueueClient`.","cause":"This error occurs when an application tries to import from the deprecated `azure.storage` meta-package instead of the service-specific `azure-storage-queue` package, or if the `azure-storage-queue` package is not correctly installed.","error":"ModuleNotFoundError: No module named 'azure.storage'"},{"fix":"Verify that the queue name is spelled correctly and exists in your Azure Storage account. If it's a new queue, ensure you call `create_queue()` or `create_queue_if_not_exists()` on the `QueueClient` or `QueueServiceClient` before attempting other operations. Also, check that the credentials (account key, SAS token, or Azure AD principal) have the necessary 'read' and 'process' permissions for queues.","cause":"This error indicates that the queue you are trying to access or perform an operation on does not exist in the specified storage account, or the credentials used do not have permission to list/access it.","error":"QueueNotFound"},{"fix":"Ensure that the content of your message, after Base64 encoding (if applicable), does not exceed 64 KB. If your data is larger, you should consider splitting it into multiple smaller messages or storing the larger data in Azure Blob Storage and sending a reference (e.g., a Blob URL) to that data in the queue message.","cause":"This error occurs when you attempt to send a message to an Azure Queue that exceeds the maximum allowed size, which is 64 KB.","error":"MessageTooLarge"},{"fix":"Ensure your connection string strictly adheres to the format: `DefaultEndpointsProtocol=https;AccountName=<account-name>;AccountKey=<account-key>;EndpointSuffix=core.windows.net`. Double-check for typos, missing semicolons, or incorrect casing. Retrieve the exact connection string from the Azure portal for accuracy.","cause":"This error arises when the connection string provided to initialize the `QueueServiceClient` or `QueueClient` is malformed, missing required parameters, or contains incorrect values.","error":"Connection string format is incorrect"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"12.15.0","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":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.08,"mem_mb":16.6,"disk_size":"43.8M"},{"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.21,"mem_mb":16.3,"disk_size":"42.7M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.8,"import_time_s":0.79,"mem_mb":16.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.83,"mem_mb":16.3,"disk_size":"43M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.26,"mem_mb":18.8,"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.44,"mem_mb":18.5,"disk_size":"46.2M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.7,"import_time_s":1.06,"mem_mb":18.8,"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.08,"mem_mb":18.5,"disk_size":"47M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.46,"mem_mb":18.7,"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.45,"mem_mb":18.5,"disk_size":"37.7M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.3,"import_time_s":1.38,"mem_mb":18.7,"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.42,"mem_mb":18.5,"disk_size":"38M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.45,"mem_mb":19.6,"disk_size":"38.6M"},{"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.43,"mem_mb":19.4,"disk_size":"37.3M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.3,"import_time_s":1.33,"mem_mb":19.6,"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.58,"mem_mb":19.4,"disk_size":"38M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.97,"mem_mb":16.3,"disk_size":"43.8M"},{"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,"mem_mb":16.2,"disk_size":"42.8M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.5,"import_time_s":1,"mem_mb":16.3,"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.99,"mem_mb":16.2,"disk_size":"43M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}