Registry / azure / azure-storage-queue

azure-storage-queue

JSON →
library12.17.0pypypi✓ verified 25d ago

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.

pip install azure-storage-queue azure-identity
INSTALL
IMPORT
SIG · AZURE-STORAGE-QUEU
A
azure-storage-queue
azurepythonv12.17.0
Install
4.4s avg
Import
893ms
Disk
43MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v12.17.0 · 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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.928s · 44.5MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 4.4s · import 0.858s · 45MB
43MB installed
● package 43MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

QueueServiceClient
from azure.storage.queue import QueueServiceClient
from azure.storage.queue import ServiceClient
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.
QueueClient
from azure.storage.queue import QueueClient
DefaultAzureCredential
from azure.identity import DefaultAzureCredential
from azure.common.credentials import ServicePrincipalCredentials
The `azure-identity` library with `DefaultAzureCredential` is the recommended modern approach for authentication, replacing older credential types and patterns in `azure.common`.
BinaryBase64EncodePolicy
from azure.storage.queue import BinaryBase64EncodePolicy
BinaryBase64DecodePolicy
from azure.storage.queue import BinaryBase64DecodePolicy

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.

import os, uuid from azure.identity import DefaultAzureCredential from azure.storage.queue import QueueServiceClient, QueueClient, BinaryBase64EncodePolicy, BinaryBase64DecodePolicy try: print('Azure Queue storage - Python quickstart sample') # Retrieve the connection string for use with the application. # The storage connection string is a key for accessing your storage account. # It is recommended to use passwordless authentication in production. connect_str = os.environ.get('AZURE_STORAGE_CONNECTION_STRING', '') queue_name = "quickstart-" + str(uuid.uuid4()) # Create the QueueServiceClient object if connect_str: # Authenticate with connection string queue_service_client = QueueServiceClient.from_connection_string( connect_str, message_encode_policy=BinaryBase64EncodePolicy(), message_decode_policy=BinaryBase64DecodePolicy() ) print("Using connection string for authentication.") else: # Authenticate with DefaultAzureCredential account_url = os.environ.get('AZURE_STORAGE_ACCOUNT_URL') # e.g., 'https://<account-name>.queue.core.windows.net' if not account_url: raise ValueError("Please set AZURE_STORAGE_CONNECTION_STRING or AZURE_STORAGE_ACCOUNT_URL environment variable.") credential = DefaultAzureCredential() queue_service_client = QueueServiceClient( account_url=account_url, credential=credential, message_encode_policy=BinaryBase64EncodePolicy(), message_decode_policy=BinaryBase64DecodePolicy() ) print("Using DefaultAzureCredential for authentication.") # Get a client to interact with the queue queue_client = queue_service_client.get_queue_client(queue_name) # Create a queue print(f"Creating queue: {queue_name}") queue_client.create_queue() # Send a message message1 = "Hello, Azure Queue!" print(f"Adding message: {message1}") queue_client.send_message(message1) message2 = "This is a second message." print(f"Adding message: {message2}") queue_client.send_message(message2) # Peek at messages print("Peeking at messages...") peeked_messages = queue_client.peek_messages(max_messages=5) for peeked_message in peeked_messages: print(f"Peeked message: {peeked_message.content}") # Receive and delete messages print("Receiving and deleting messages...") messages = queue_client.receive_messages(messages_per_page=1) for message in messages: print(f"Received message: {message.content}") queue_client.delete_message(message) print(f"Deleted message: {message.content}") print(f"Successfully completed the quickstart. Deleting queue: {queue_name}") queue_client.delete_queue() except Exception as ex: print(f"Exception: {ex}")
Debug
Known issues
breakingMajor 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.
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.
affects: All versions prior to 12.0.0
gotchaMessages 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.
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.
affects: All versions
gotchaAzure 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.
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.
affects: All versions
gotchaUsing shared access keys or connection strings directly in application code is discouraged, especially in production. This poses a security risk and complicates key rotation.
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.
affects: All versions
gotchaIncorrectly 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.
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.
affects: All versions
breakingThe 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.
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.
affects: All versions
Upgrade
Version history
12.17.0latest on PyPI · released Jun 8, 2026
Audit
Dependencies
azure-identityrequiredRecommended for passwordless authentication to Azure services, which is the preferred and more secure authentication method for production environments.
Agent activity
32 hits · last 30 days
node
26
OpenAI (training)
1
Resources
azure-storage-queue — pip install azure-storage-queue · libregistry