How to use Azure Queue storage v2.1 from Python

This article demonstrates common scenarios using the Azure Queue storage service. The scenarios covered include inserting, peeking, getting, and deleting queue messages, and creating and deleting queues.


Try the Microsoft Azure Storage Explorer

Microsoft Azure Storage Explorer is a free, standalone app from Microsoft that enables you to work visually with Azure Storage data on Windows, macOS, and Linux.


The samples in this article are written in Python and use the Microsoft Azure Storage SDK for Python. For more information on queues, see the Next steps section.

What is Queue storage?

Azure Queue storage is a service for storing large numbers of messages that can be accessed from anywhere in the world via authenticated calls using HTTP or HTTPS. A single queue message can be up to 64 KB in size, and a queue can contain millions of messages, up to the total capacity limit of a storage account. Queue storage is often used to create a backlog of work to process asynchronously.

Queue service concepts

The Azure Queue service contains the following components:

Azure Queue service components

  • URL format: Queues are addressable using the following URL format: http://<storage account><queue>

    The following URL addresses a queue in the diagram:

  • Storage Account: All access to Azure Storage is done through a storage account. For more information about storage accounts, see Storage account overview.

  • Queue: A queue contains a set of messages. All messages must be in a queue. Note that the queue name must be all lowercase. For information on naming queues, see Naming Queues and Metadata.

  • Message: A message, in any format, of up to 64 KB. The maximum time that a message can remain in the queue is 7 days. For version 2017-07-29 or later, the maximum time-to-live can be any positive number, or -1 indicating that the message doesn't expire. If this parameter is omitted, the default time-to-live is seven days.

Create an Azure storage account

The easiest way to create your first Azure storage account is by using the Azure portal. To learn more, see Create a storage account.

You can also create an Azure storage account by using Azure PowerShell, Azure CLI, or the Azure Storage Resource Provider for .NET.

If you prefer not to create a storage account in Azure at this time, you can also use the Azure storage emulator to run and test your code in a local environment. For more information, see Use the Azure Storage Emulator for Development and Testing.

Download and install Azure Storage SDK for Python

The Azure Storage SDK for Python requires Python version 2.7, 3.3, or later.

Install via PyPi

To install via the Python Package Index (PyPI), type:

pip install azure-storage-queue==2.1.0


If you are upgrading from the Azure Storage SDK for Python version 0.36 or earlier, uninstall the older SDK using pip uninstall azure-storage before installing the latest package.

For alternative installation methods, see Azure Storage SDK for Python.

View the sample application

To view and run a sample application that shows how to use Python with Azure Queues, see Azure Storage: Getting Started with Azure Queues in Python.

To run the sample application, make sure you have installed both the azure-storage-queue and azure-storage-common packages.

Create a queue

The QueueService object lets you work with queues. The following code creates a QueueService object. Add the following near the top of any Python file in which you wish to programmatically access Azure Storage:

from import QueueService

The following code creates a QueueService object using the storage account name and account key. Replace myaccount and mykey with your account name and key.

queue_service = QueueService(account_name='myaccount', account_key='mykey')


Insert a message into a queue

To insert a message into a queue, use the put_message method to create a new message and add it to the queue.

queue_service.put_message('taskqueue', u'Hello World')

Azure queue messages are stored as text. If you want to store binary data, setup Base64 encoding and decoding functions on the queue service object before putting a message in the queue.

# setup queue Base64 encoding and decoding functions
queue_service.encode_function = QueueMessageFormat.binary_base64encode
queue_service.decode_function = QueueMessageFormat.binary_base64decode

Peek at the next message

You can peek at the message in the front of a queue without removing it from the queue by calling the peek_messages method. By default, peek_messages peeks at a single message.

messages = queue_service.peek_messages('taskqueue')
for message in messages:

Dequeue messages

Your code removes a message from a queue in two steps. When you call get_messages, you get the next message in a queue by default. A message returned from get_messages becomes invisible to any other code reading messages from this queue. By default, this message stays invisible for 30 seconds. To finish removing the message from the queue, you must also call delete_message. This two-step process of removing a message assures that when your code fails to process a message due to hardware or software failure, another instance of your code can get the same message and try again. Your code calls delete_message right after the message has been processed.

messages = queue_service.get_messages('taskqueue')
for message in messages:
    queue_service.delete_message('taskqueue',, message.pop_receipt)

There are two ways you can customize message retrieval from a queue. First, you can get a batch of messages (up to 32). Second, you can set a longer or shorter invisibility timeout, allowing your code more or less time to fully process each message. The following code example uses the get_messages method to get 16 messages in one call. Then it processes each message using a for loop. It also sets the invisibility timeout to five minutes for each message.

messages = queue_service.get_messages(
    'taskqueue', num_messages=16, visibility_timeout=5*60)
for message in messages:
    queue_service.delete_message('taskqueue',, message.pop_receipt)

Change the contents of a queued message

You can change the contents of a message in-place in the queue. If the message represents a work task, you could use this feature to update the status of the work task. The code below uses the update_message method to update a message. The visibility timeout is set to 0, meaning the message appears immediately and the content is updated.

messages = queue_service.get_messages('taskqueue')
for message in messages:
        'taskqueue',, message.pop_receipt, 0, u'Hello World Again')

Get the queue length

You can get an estimate of the number of messages in a queue. The get_queue_metadata method asks the queue service to return metadata about the queue, and the approximate_message_count. The result is only approximate because messages can be added or removed after the queue service responds to your request.

metadata = queue_service.get_queue_metadata('taskqueue')
count = metadata.approximate_message_count

Delete a queue

To delete a queue and all the messages contained in it, call the delete_queue method.


Next steps

Now that you've learned the basics of queue storage, follow these links to learn more.