Azure Storage File Share

12.24.0 · active · verified Sun Mar 29

Microsoft Azure Azure File Share Storage Client Library for Python version 12.24.0. This library provides fully managed file shares in the cloud, accessible via the industry-standard Server Message Block (SMB) protocol. It is part of the extensive Azure SDK for Python, which typically adheres to a continuous release cadence, delivering frequent updates and bug fixes across its various client libraries.

Warnings

breaking Version 12.x represents a complete redesign from previous versions (e.g., v2.x) of the Azure Storage SDK. The package `azure-storage` is deprecated, and users must now install service-specific packages like `azure-storage-file-share`. Client class names, API patterns, and module structures have changed significantly.
Fix: Migrate code to use the new v12 client libraries and their specific import paths and API patterns. Refer to the official migration guides for detailed steps.
gotcha While `DefaultAzureCredential` (OAuth tokens via Azure AD) is generally the recommended and most secure authentication method for Azure SDKs, it is not always supported for all data plane operations at the file share level, such as creating share snapshots.
Fix: For operations that do not support OAuth, use an account key or a connection string for authentication. This is explicitly stated in the documentation for certain scenarios like share snapshots. Consider using Azure Key Vault to securely store account keys.
gotcha Asynchronous clients (`azure.storage.fileshare.aio`) require an async HTTP transport library, such as `aiohttp`, to be explicitly installed. Without it, attempting to use async clients will result in runtime errors.
Fix: Install `aiohttp` (e.g., `pip install azure-storage-file-share[aio]`) to enable asynchronous operations. Ensure async clients and credentials are properly closed when no longer needed using `await client.close()` or `async with` statements.
gotcha A common error, `ResourceNotFoundError` (or `ParentNotFound` in older versions/similar contexts), occurs if the specified file share, directory, or parent path does not exist when attempting to interact with a file or subdirectory.
Fix: Always ensure the parent share and any intermediate directories exist before attempting to create or access files within them. You can use methods like `create_share()` or `create_directory()` on the respective client objects to ensure existence.

Install

pip install azure-storage-file-share Install stable version
pip install azure-storage-file-share[aio] Install with async support

Imports

ShareServiceClient
```
from azure.storage.fileshare import ShareServiceClient
```
The v2 SDK used a monolithic `azure.storage` package with different client classes (e.g., `FileService`). V12 uses service-specific packages and client names.

ShareClient

from azure.storage.fileshare import ShareClient

ShareDirectoryClient

from azure.storage.fileshare import ShareDirectoryClient

ShareFileClient

from azure.storage.fileshare import ShareFileClient

Quickstart

This quickstart demonstrates how to initialize a `ShareServiceClient` using a storage account connection string and then list all existing file shares in the account. Ensure the `STORAGE_CONNECTION_STRING` environment variable is set with your Azure Storage account connection string.

import os
from azure.storage.fileshare import ShareServiceClient
from azure.core.exceptions import ResourceNotFoundError

# Retrieve the connection string from an environment variable
# Go to Azure Portal -> Storage Accounts -> your_storage_account -> Access keys
# Copy the 'Connection string' value
connection_string = os.environ.get("STORAGE_CONNECTION_STRING", "DefaultEndpointsProtocol=https;AccountName=YOUR_ACCOUNT_NAME;AccountKey=YOUR_ACCOUNT_KEY;EndpointSuffix=core.windows.net")

if "YOUR_ACCOUNT_NAME" in connection_string or "YOUR_ACCOUNT_KEY" in connection_string:
    print("Please set the STORAGE_CONNECTION_STRING environment variable or replace placeholder values in the quickstart code.")
    exit(1)

try:
    # Create the ShareServiceClient object from a connection string
    service_client = ShareServiceClient.from_connection_string(connection_string)

    # List shares in the storage account
    print("Listing shares in the storage account:")
    for share in service_client.list_shares():
        print(f"- {share.name}")

    print("\nSuccessfully listed file shares.")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →