Azure Storage File Share

12.24.0 · active · verified Tue Apr 07

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.

Common errors

```
ModuleNotFoundError: No module named 'azure.storage'
```
cause This error occurs when the deprecated `azure-storage` meta-package is installed, or when the `azure-storage-file-share` package (or its specific components like `azure.storage.fileshare`) is not installed or incorrectly imported. The `azure.storage` package was a meta-package that has been deprecated in favor of service-specific packages like `azure-storage-blob`, `azure-storage-file-share`, etc.

fix Ensure you install the correct, service-specific package for file shares: `pip install azure-storage-file-share`. Then, import clients directly from `azure.storage.fileshare`, for example: `from azure.storage.fileshare import ShareServiceClient`.
```
azure.core.exceptions.ResourceNotFoundError: The specified resource does not exist
```
cause This error indicates that the file share, directory, or file you are trying to access or manipulate (e.g., upload to, download from, or list) does not exist in the specified path, or your credentials do not have sufficient permissions to see it. For file uploads, it can also mean you're trying to set content on a file that hasn't been created yet.

fix Verify the share name, directory path, and file name are correct and exist in your Azure Storage account. Ensure the credentials (account key, SAS token, or Azure AD principal) have the necessary permissions (e.g., read, write, create) for the resource. When uploading a file, first ensure the parent directory exists, and for some operations, you may need to explicitly create the file (e.g., using `create_file()`) before uploading its content.
```
AuthenticationFailed: Server failed to authenticate the request. Make sure the value of Authorization header is formed correctly including the signature.
```
cause This common error signifies an issue with authentication. It's often caused by an incorrect storage account name or key, an expired or malformed Shared Access Signature (SAS) token, or a significant time skew between the client and the Azure Storage service. Insufficient RBAC permissions for a Managed Identity can also lead to this.

fix Double-check your storage account name and access key. If using a SAS token, regenerate it to ensure it's valid, has the correct permissions, and a non-expired expiry time. Synchronize your system's clock with UTC. If using Azure AD or Managed Identity, verify that the assigned RBAC roles (e.g., 'Storage File Data SMB Share Contributor' or 'Storage File Data Reader') are correctly scoped to the storage account or file share.
```
azure.core.exceptions.ClientAuthenticationError: (MissingRequiredHeader) HeaderName: x-ms-file-request-intent
```
cause This error occurs when authenticating with OAuth tokens (like Managed Identity or Azure AD credentials) for certain Azure File Share operations, where the `x-ms-file-request-intent` header is explicitly required by the service but is not automatically included by the SDK or explicitly set in your client configuration. This is often the case for administrative or backup-related operations.

fix When creating the `ShareServiceClient` or `ShareClient` with `TokenCredential` (e.g., `DefaultAzureCredential`), you need to pass `token_intent='backup'` as a keyword argument to the client constructor. Example: `ShareServiceClient(account_url=account_url, credential=azure_credential, token_intent='backup')`. Ensure your Azure AD principal has the necessary RBAC permissions for the intended operations.

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
wrong:
```
from azure.storage import FileService
```
correct:
```
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 →