Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Azure Storage Blobs client library for Python

Azure Blob storage is Microsoft's object storage solution for the cloud. Blob storage is optimized for storing massive amounts of unstructured data, such as text or binary data.

Blob storage is ideal for:

  • Serving images or documents directly to a browser
  • Storing files for distributed access
  • Streaming video and audio
  • Storing data for backup and restore, disaster recovery, and archiving
  • Storing data for analysis by an on-premises or Azure-hosted service

Source code | Package (PyPi) | API reference documentation | Product documentation | Samples

Getting started

Install the package

Install the Azure Storage Blobs client library for Python with pip:

pip install azure-storage-blob --pre

Prerequisites: You must have an Azure subscription, and a Storage Account to use this package.

To create a Storage Account, you can use the Azure Portal, Azure PowerShell or Azure CLI:

az storage account create -n MyStorageAccountName -g MyResourceGroupName

Requires Python 2.7, 3.5 or later to use this package.

Authenticate the client

Interaction with Storage Blobs starts with an instance of the BlobServiceClient class. You need an existing storage account, its URL, and a credential to instantiate the client object.

Get credentials

To authenticate the client you have a few options:

  1. Use a SAS token string
  2. Use an account shared access key
  3. Use a token credential from azure.identity

Alternatively, you can authenticate with a storage connection string using the from_connection_string method. See example: Client creation with a connection string.

You can omit the credential if your account URL already has a SAS token.

Create client

Once you have your account URL and credentials ready, you can create the BlobServiceClient:

from azure.storage.blob import BlobServiceClient

service = BlobServiceClient(account_url="https://<my-storage-account-name>.blob.core.windows.net/", credential=credential)

Key concepts

Blob storage offers three types of resources:

  • The storage account
  • A container in the storage account
  • A blob in a container

Clients

The Storage Blobs SDK provides four different clients to interact with the Blob Service:

  1. BlobServiceClient - this client interacts with the Blob Service at the account level. It provides operations to retrieve and configure the account properties as well as list, create, and delete containers within the account. For operations relating to a specific container or blob, clients for those entities can also be retrieved using the get_blob_client or get_container_client functions.
  2. ContainerClient - this client represents interaction with a specific container, although that container need not exist yet. It provides operations to create, delete, or configure containers and includes operations to list, upload, and delete blobs in the container. For operations relating to a specific blob, the client can also be retrieved using the get_blob_client function.
  3. BlobClient - this client represents interaction with a specific blob, although that blob need not exist yet. It provides blob operations to upload, download, delete, create snapshots, and list blobs, as well as specific operations per blob type.
  4. LeaseClient - this client represents lease interactions with a ContainerClient or BlobClient. It provides operations to acquire, renew, release, change, and break leases on the resources.

Blob Types

Once you've initialized a Client, you can choose from the different types of blobs:

  • Block blobs store text and binary data, up to about 4.7 TB. Block blobs are made up of blocks of data that can be managed individually
  • Append blobs are made up of blocks like block blobs, but are optimized for append operations. Append blobs are ideal for scenarios such as logging data from virtual machines
  • Page blobs store random access files up to 8 TB in size. Page blobs store virtual hard drive (VHD) files and serve as disks for Azure virtual machines

For more information about the different types of blobs, see Understanding Block Blobs, Append Blobs, and Page Blobs

Examples

The following sections provide several code snippets covering some of the most common Storage Blob tasks, including:

Client creation with a connection string

Create the BlobServiceClient using the connection string to your Azure Storage account.

from azure.storage.blob import BlobServiceClient

service = BlobServiceClient.from_connection_string(conn_str="my_connection_string")

Uploading a blob

Upload a blob to your container.

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string("my_connection_string", container="mycontainer", blob="my_blob")

with open("./SampleSource.txt", "rb") as data:
    blob.upload_blob(data)

Use the async client to upload a blob to your container.

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string("my_connection_string", container="mycontainer", blob="my_blob")

with open("./SampleSource.txt", "rb") as data:
    await blob.upload_blob(data)

Downloading a blob

Download a blob from your container.

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string("my_connection_string", container="mycontainer", blob="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    blob_data = blob.download_blob()
    my_blob.writelines(blob_data.content_as_bytes())

Download a blob asynchronously.

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string("my_connection_string", container="mycontainer", blob="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    stream = await blob.download_blob()
    data = await stream.content_as_bytes()
    my_blob.write(data)

Enumerating blobs

List the blobs in your container.

from azure.storage.blob import ContainerClient

container = ContainerClient.from_connection_string("my_connection_string", container="mycontainer")

blob_list = container.list_blobs()
for blob in blob_list:
    print(blob.name + '\n')

List the blobs asynchronously.

from azure.storage.blob.aio import ContainerClient

container = ContainerClient.from_connection_string("my_connection_string", container="mycontainer")

blob_list = [] 
async for blob in container.list_blobs():
    blob_list.append(blob)
print(blob_list)

Troubleshooting

Storage Blob clients raise exceptions defined in Azure Core.

All Blob service operations will throw a StorageErrorException on failure with helpful error codes.

Next steps

More sample code

Get started with our Blob samples.

Several Storage Blobs Python SDK samples are available to you in the SDK's GitHub repository. These samples provide example code for additional scenarios commonly encountered while working with Storage Blobs:

  • test_blob_samples_hello_world.py (async version) - Examples for common Storage Blob tasks:

    • Set up a container
    • Create a block, page, or append blob
    • Upload blobs
    • Download blobs
    • Delete blobs
  • test_blob_samples_authentication.py (async version) - Examples for authenticating and creating the client:

    • From a connection string
    • From a shared access key
    • From a shared access signature token
    • From active directory
  • test_blob_samples_service.py (async version) - Examples for interacting with the blob service:

    • Get account information
    • Get and set service properties
    • Get service statistics
    • Create, list, and delete containers
    • Get the Blob or Container client
  • test_blob_samples_containers.py (async version) - Examples for interacting with containers:

    • Create a container and delete containers
    • Set metadata on containers
    • Get container properties
    • Acquire a lease on container
    • Set an access policy on a container
    • Upload, list, delete blobs in container
    • Get the blob client to interact with a specific blob
  • test_blob_samples_common.py (async version) - Examples common to all types of blobs:

    • Create a snapshot
    • Delete a blob snapshot
    • Soft delete a blob
    • Undelete a blob
    • Acquire a lease on a blob
    • Copy a blob from a URL

Additional documentation

For more extensive documentation on the Azure Storage Blobs, see the Azure Storage Blobs documentation on docs.microsoft.com.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Metadata

Release files for azure-storage-blob 12.0.0b4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for azure-storage-blob 12.0.0b4
File Size Uploaded Provenance Actions
azure-storage-blob-12.0.0b4.zip 24.0 MB Without provenance Details for azure-storage-blob-12.0.0b4.zip

Built distribution (wheel)

Table of built distributions (wheels) for azure-storage-blob 12.0.0b4
File Interpreter ABI Platform Actions
azure_storage_blob-12.0.0b4-py2.py3-none-any.whl Python 3, Python 2 none any Details for azure_storage_blob-12.0.0b4-py2.py3-none-any.whl

Total release size: 24.3 MB

Release files / azure-storage-blob-12.0.0b4.zip

Download URL azure-storage-blob-12.0.0b4.zip
Size 24.0 MB
Tags Source
SHA-256 checksum
How to use checksums
5155dd00a1e29c12e61d9d5a68a2ee0f82295e756aeb02dd4e4b5f09b1cea941
BLAKE2b-256 checksum
How to use checksums
29bd4ba14492555a8f55643036f857b7c4be810181d78f3b25d4a18680e43fc3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/2.0.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.36.1 CPython/3.7.4

Release files / azure_storage_blob-12.0.0b4-py2.py3-none-any.whl

Download URL azure_storage_blob-12.0.0b4-py2.py3-none-any.whl
Size 264.8 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
c07390afe80fee37053519daf1edcd1d91cb8b7d678b5698929383aac0dc4e78
BLAKE2b-256 checksum
How to use checksums
66251919070ec8d09b20ee068e14b05a8dcac6f12a63d736935089197dbd4f0f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/2.0.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.36.1 CPython/3.7.4

Security for azure-storage-blob 12.0.0b4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page