Quickstart: Upload, download, and list blobs with Python

In this quickstart, you see how to use Python to upload, download, and list block blobs in a container in Azure Blob storage. Blobs are simply objects that can hold any amount of text or binary data (such as images, documents, streaming media, archive data, etc.), and are distinct in Azure Storage from file shares, schemaless tables, and message queues. (For more information, see Introduction to Azure Storage.)


The features described in this article are available to accounts that have a hierarchical namespace only if you enroll in the public preview of multi-protocol access on Data Lake Storage. To review limitations, see the known issues article.


To access Azure Storage, you'll need an Azure subscription. If you don't already have a subscription, then create a free account before you begin.

All access to Azure Storage takes place through a storage account. For this quickstart, create a storage account using the Azure portal, Azure PowerShell, or Azure CLI. For help creating the account, see Create a storage account.

Make sure you have the following additional prerequisites installed:

Download the sample application

The sample application in this quickstart is a basic Python application.

Use git to download a copy of the application to your development environment.

git clone https://github.com/Azure-Samples/storage-blobs-python-quickstart.git 

This command clones the Azure-Samples/storage-blobs-python-quickstart repository to your local git folder. To run the Python program, open the example.py file at the root of the repository.

Copy your credentials from the Azure portal

The sample application needs to authorize access to your storage account. Provide your storage account credentials to the application in the form of a connection string. To view your storage account credentials:

  1. Sign in to the Azure portal.

  2. Locate your storage account.

  3. In the Settings section of the storage account overview, select Access keys. Your account access keys and connection string are displayed.

  4. Note the name of your storage account, which you'll need for authorization.

  5. Find the Key value under key1, and select Copy to copy the account key.

    Screenshot showing how to copy your account key from the Azure portal

Configure your storage connection string

In the application, provide your storage account name and account key to create a BlockBlobService object. Open the example.py file from the Solution Explorer in your IDE. Replace the accountname and accountkey values with your account name and key.

block_blob_service = BlockBlobService(
    account_name='accountname', account_key='accountkey')

Run the sample

This sample creates a test file in the Documents folder. The sample program uploads the test file to Blob storage, lists the blobs in the container, and downloads the file with a new name.

First, install the dependencies by running pip install:

    pip install azure-storage-blob

Next, run the sample. You’ll see messages similar to the following output:

Temp file = C:\Users\azureuser\Documents\QuickStart_9f4ed0f9-22d3-43e1-98d0-8b2c05c01078.txt

Uploading to Blob storage as blobQuickStart_9f4ed0f9-22d3-43e1-98d0-8b2c05c01078.txt

List blobs in the container
         Blob name: QuickStart_9f4ed0f9-22d3-43e1-98d0-8b2c05c01078.txt

Downloading blob to C:\Users\azureuser\Documents\QuickStart_9f4ed0f9-22d3-43e1-98d0-8b2c05c01078_DOWNLOADED.txt

Before you continue, look in your Documents folder for the two files. You can open them and see they're the same.

You can also use a tool such as the Azure Storage Explorer to view the files in Blob storage. Azure Storage Explorer is a free cross-platform tool that allows you to access your storage account information.

After you've verified the files, press any key to finish the demo and delete the test files. Now that you know what the sample does, open the example.py file to look at the code.

Understand the sample code

Let’s walk through the sample code to understand how it works.

Get references to the storage objects

First, you create the references to the objects used to access and manage Blob storage. These objects build on each other, and each is used by the next one in the list.

  • Instantiate the BlockBlobService object, which points to the Blob service in your storage account.

  • Instantiate the CloudBlobContainer object, which represents the container you're accessing. Containers are used to organize your blobs like you use folders on your computer to organize your files.

Once you have the Cloud Blob container, instantiate the CloudBlockBlob object that points to the specific blob that you're interested in. You can then upload, download, and copy the blob as you need.


Container names must be lowercase. For more information about container and blob names, see Naming and referencing Containers, Blobs, and Metadata.

In this section, you instantiate the objects, create a new container, and then set permissions on the container so the blobs are public. The container is called quickstartblobs.

# Create the BlockBlockService that is used to call the Blob service for the storage account.
block_blob_service = BlockBlobService(
    account_name='accountname', account_key='accountkey')

# Create a container called 'quickstartblobs'.
container_name = 'quickstartblobs'

# Set the permission so the blobs are public.
    container_name, public_access=PublicAccess.Container)

Upload blobs to the container

Blob storage supports block blobs, append blobs, and page blobs. Block blobs are the most commonly used, and that's what is used in this quickstart.

To upload a file to a blob, get the full file path by joining the directory name with the file name on your local drive. You can then upload the file to the specified path using the create_blob_from_path method.

The sample code creates a local file to be used for the upload and download, storing the file to be uploaded as full_path_to_file and the name of the blob as local_file_name. The following example uploads the file to your container called quickstartblobs.

# Create a file in Documents to test the upload and download.
local_path = os.path.expanduser("~\Documents")
local_file_name = "QuickStart_" + str(uuid.uuid4()) + ".txt"
full_path_to_file = os.path.join(local_path, local_file_name)

# Write text to the file.
file = open(full_path_to_file, 'w')
file.write("Hello, World!")

print("Temp file = " + full_path_to_file)
print("\nUploading to Blob storage as blob" + local_file_name)

# Upload the created file, use local_file_name for the blob name.
    container_name, local_file_name, full_path_to_file)

There are several upload methods that you can use with Blob storage. For example, if you have a memory stream, you can use the create_blob_from_stream method rather than create_blob_from_path.

Block blobs can be as large as 4.7 TB, and can be anything from Excel spreadsheets to large video files. Page blobs are primarily used for the VHD files that back IaaS VMs. Append blobs are used for logging, such as when you want to write to a file and then keep adding more information. Most objects stored in Blob storage are block blobs.

List the blobs in a container

Get a list of files in the container with the list_blobs method. This method returns a generator. The following code retrieves the list of blobs—then loops through them—showing the names of the blobs found in a container.

# List the blobs in the container.
print("\nList blobs in the container")
generator = block_blob_service.list_blobs(container_name)
for blob in generator:
    print("\t Blob name: " + blob.name)

Download the blobs

Download blobs to your local disk using the get_blob_to_path method. The following code downloads the blob uploaded in a previous section. _DOWNLOADED is added as a suffix to the blob name so you can see both files on local disk.

# Download the blob(s).
# Add '_DOWNLOADED' as prefix to '.txt' so you can see both files in Documents.
full_path_to_file2 = os.path.join(local_path, string.replace(
    local_file_name, '.txt', '_DOWNLOADED.txt'))
print("\nDownloading blob to " + full_path_to_file2)
    container_name, local_file_name, full_path_to_file2)

Clean up resources

If you no longer need the blobs uploaded in this quickstart, you can delete the entire container using the delete_container method. To delete individual files instead, use the delete_blob method.

# Clean up resources. This includes the container and the temp files.

Resources for developing Python applications with blobs

For more information about Python development with Blob storage, see these additional resources:

Binaries and source code

Client library reference and samples

Next steps

In this quickstart, you learned how to transfer files between a local disk and Azure Blob storage using Python. To learn more about working with Blob storage, continue to the Blob storage How-to.

For more information about the Storage Explorer and Blobs, see Manage Azure Blob storage resources with Storage Explorer.