Azure Blob Storage SDK for Python: Cloud File Operations Made Simple

If you need cloud-based object storage for Python applications, Azure Blob Storage is one of your best options. The Python SDK makes it remarkably easy to upload, download, and manage files at any scale—from quick automation scripts to production web applications handling millions of files.

What This Skill Does

The azure-storage-blob-py skill provides a Pythonic interface to Azure Blob Storage, Microsoft's object storage solution for unstructured data. Think of it as a massively scalable file system accessible via clean, intuitive Python APIs.

The SDK offers three client types that form a hierarchy: BlobServiceClient for account-level operations (creating containers, listing all blobs), ContainerClient for container management (think of containers as top-level folders), and BlobClient for individual blob operations (upload, download, delete specific files). This hierarchy makes navigation logical and code readable.

You can authenticate with connection strings, shared access signatures (SAS tokens), or Azure AD credentials via DefaultAzureCredential. The SDK handles chunked uploads and downloads automatically, supports async operations for high-performance applications, manages metadata and properties, implements parallel transfers for speed, and provides both synchronous and asynchronous APIs so you can choose based on your needs.

Getting Started

Install the SDK and Azure identity library:

pip install azure-storage-blob azure-identity

Set your storage account name (or full URL) as an environment variable:

export AZURE_STORAGE_ACCOUNT_URL="https://mystorage.blob.core.windows.net"

Here's the quickest path from nothing to uploading your first file:

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

# Connect to storage account
credential = DefaultAzureCredential()
account_url = "https://mystorage.blob.core.windows.net"
blob_service_client = BlobServiceClient(account_url, credential=credential)

# Create container (like a folder)
container_client = blob_service_client.get_container_client("myfiles")
container_client.create_container()

# Upload a file
blob_client = blob_service_client.get_blob_client(container="myfiles", blob="document.txt")
with open("local-file.txt", "rb") as data:
    blob_client.upload_blob(data, overwrite=True)

# Download the file
download_stream = blob_client.download_blob()
with open("downloaded.txt", "wb") as file:
    file.write(download_stream.readall())

print("Upload and download complete!")

That's the basic pattern: get a service client, navigate to the container and blob you want, then call upload_blob() or download_blob(). Simple.

Key Features

Clean Client Hierarchy: The three-tier client structure (BlobServiceClient → ContainerClient → BlobClient) mirrors how you conceptually think about storage. Account contains containers, containers contain blobs. Your code reflects this structure naturally.

Flexible Upload Sources: Upload from file paths, byte strings, streams, or any file-like object. The SDK adapts to whatever data source you have. This makes it easy to integrate into existing data pipelines.

Efficient Streaming: For large files, stream data instead of loading everything into memory. Use readinto() to download directly into buffers, or iterate over chunks. This keeps memory usage constant regardless of file size.

Parallel Transfers: Configure max_concurrency to upload or download files in parallel chunks. This can dramatically speed up large file operations, especially over high-bandwidth connections.

Async Support: A complete async API (using async/await) enables high-performance applications to handle thousands of concurrent operations efficiently. Perfect for web services and data processing pipelines.

Metadata and Properties: Attach custom metadata (key-value pairs) to any blob, query blob properties like size and last modified time, and set HTTP headers like Content-Type and Cache-Control for web-served content.

Hierarchical Listing: While blob storage is flat, the SDK supports hierarchical navigation with prefixes and delimiters. Use walk_blobs() to navigate virtual directory structures naturally.

Usage Examples

Upload Files with Metadata and Content Type:

from azure.storage.blob import ContentSettings

blob_client = container_client.get_blob_client("reports/2026/sales.csv")

metadata = {
    "department": "sales",
    "quarter": "Q1",
    "year": "2026"
}

content_settings = ContentSettings(
    content_type="text/csv",
    content_encoding="utf-8",
    cache_control="max-age=3600"
)

with open("sales-report.csv", "rb") as data:
    blob_client.upload_blob(
        data,
        overwrite=True,
        metadata=metadata,
        content_settings=content_settings,
        max_concurrency=4  # Parallel upload
    )

print("Uploaded with metadata and proper Content-Type")

List Blobs with Prefix Filtering:

# List all blobs in a "folder"
container_client = blob_service_client.get_container_client("logs")

print("Files in logs/2026/01/:")
for blob in container_client.list_blobs(name_starts_with="2026/01/"):
    print(f"  {blob.name} ({blob.size:,} bytes)")

# Walk hierarchical structure (virtual directories)
print("\nDirectory structure:")
for item in container_client.walk_blobs(name_starts_with="2026/", delimiter="/"):
    if item.get("prefix"):
        print(f"📁 {item['prefix']}")
    else:
        print(f"📄 {item.name}")

Download Large Files Efficiently:

import io

blob_client = container_client.get_blob_client("datasets/large-file.csv")

# Stream download without loading entire file into memory
output_file = "local-copy.csv"

with open(output_file, "wb") as file:
    download_stream = blob_client.download_blob(max_concurrency=4)
    
    # Process in chunks
    for chunk in download_stream.chunks():
        file.write(chunk)
        # Could process chunk here instead of writing

print(f"Downloaded to {output_file}")

Async Upload for High-Performance Applications:

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient
import asyncio

async def upload_multiple_files(files):
    """Upload multiple files concurrently."""
    credential = DefaultAzureCredential()
    account_url = "https://mystorage.blob.core.windows.net"
    
    async with BlobServiceClient(account_url, credential=credential) as client:
        container_client = client.get_container_client("uploads")
        
        # Upload all files concurrently
        tasks = []
        for file_path in files:
            blob_client = container_client.get_blob_client(file_path)
            with open(file_path, "rb") as data:
                content = data.read()
                tasks.append(blob_client.upload_blob(content, overwrite=True))
        
        await asyncio.gather(*tasks)
        print(f"Uploaded {len(files)} files concurrently")

# Upload 10 files in parallel
files = [f"file{i}.txt" for i in range(10)]
asyncio.run(upload_multiple_files(files))

Generate SAS Token for Temporary Access:

from datetime import datetime, timedelta, timezone
from azure.storage.blob import generate_blob_sas, BlobSasPermissions

# Generate SAS token with read permission for 1 hour
sas_token = generate_blob_sas(
    account_name="mystorage",
    container_name="public",
    blob_name="document.pdf",
    account_key="your-account-key",
    permission=BlobSasPermissions(read=True),
    expiry=datetime.now(timezone.utc) + timedelta(hours=1)
)

# Create full URL with SAS token
blob_url = f"https://mystorage.blob.core.windows.net/public/document.pdf?{sas_token}"
print(f"Share this URL (expires in 1 hour): {blob_url}")

Query Blob Properties and Metadata:

blob_client = container_client.get_blob_client("data/sample.json")

# Get all properties
properties = blob_client.get_blob_properties()

print(f"Blob: {properties.name}")
print(f"Size: {properties.size:,} bytes")
print(f"Content-Type: {properties.content_settings.content_type}")
print(f"Last modified: {properties.last_modified}")
print(f"ETag: {properties.etag}")

# Access custom metadata
if properties.metadata:
    print("Metadata:")
    for key, value in properties.metadata.items():
        print(f"  {key}: {value}")

Best Practices

Use DefaultAzureCredential in Production: Avoid hardcoding connection strings or account keys. Use DefaultAzureCredential which automatically tries various authentication methods (managed identity, environment variables, Azure CLI). This is more secure and works seamlessly across local development and cloud deployment.

Always Specify overwrite=True When Replacing Files: By default, upload_blob() fails if a blob already exists. Be explicit: use overwrite=True when you want to replace, omit it when you want to prevent accidental overwrites.

Enable Parallel Transfers for Large Files: Set max_concurrency to 4-8 for files over 10MB. The SDK automatically chunks the file and transfers blocks in parallel, dramatically improving speed on fast networks.

Use Streaming for Large Downloads: Don't call readall() on multi-gigabyte files—you'll run out of memory. Use chunks() to process data incrementally or readinto() to write directly to a file or buffer.

Set Appropriate Content Types: When uploading files that will be served over HTTP (images, PDFs, videos), always set the Content-Type header. Browsers rely on this to handle files correctly. The SDK doesn't auto-detect content types.

Implement Retry Logic: While the SDK has built-in retries, add application-level retry logic for critical operations. Network issues happen. Use exponential backoff for resilience.

Use walk_blobs() for Directory Navigation: When you need to list blobs hierarchically (by "folder"), use walk_blobs(delimiter="/") instead of filtering with list_blobs(). It's more efficient and easier to work with.

When to Use This Skill

Perfect for:

• File upload/download features in web applications


• Data lake storage for analytics and machine learning


• Backup and archival systems


• Serving static content (images, videos, documents)


• Log aggregation and processing


• Distributed data processing pipelines


• Content delivery workflows with CDN integration

Consider alternatives for:

• Structured data requiring complex queries (use Azure Cosmos DB or SQL Database)


• Message queuing with ordering guarantees (use Azure Service Bus)


• File shares with SMB/NFS protocols (use Azure Files)


• Transactional file operations (use Azure Files or a database)


• Sub-millisecond latency requirements (use Azure Cache for Redis)

Blob Storage is unbeatable for storing massive amounts of unstructured data cheaply and reliably. If you need filesystem semantics, ACID transactions, or complex querying, look elsewhere.

Related Skills

Explore the full Azure Blob Storage Python SDK skill: /ai-assistant/azure-storage-blob-py

Source

This skill is provided by Microsoft as part of the Azure SDK for Python (package: azure-storage-blob).

---

Ready to build cloud-native file storage into your Python applications? Azure Blob Storage offers the scalability and simplicity you need.