Azure Storage File Share
raw JSON → 12.24.0 verified Tue May 12 auth: no python install: verified
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.
pip install azure-storage-file-share Common errors
error 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. error 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. error 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.
error 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[aio] Install compatibility verified last tested: 2026-05-12
python os / libc variant status wheel install import disk
3.10 alpine (musl) azure-storage-file-share wheel - 1.04s 42.9M
3.10 alpine (musl) azure-storage-file-share - - 1.13s 41.8M
3.10 alpine (musl) aio wheel - 1.26s 51.1M
3.10 alpine (musl) aio - - 1.28s 50.3M
3.10 slim (glibc) azure-storage-file-share wheel 3.4s 0.78s 43M
3.10 slim (glibc) azure-storage-file-share - - 1.18s 42M
3.10 slim (glibc) aio wheel 6.4s 0.92s 53M
3.10 slim (glibc) aio - - 0.95s 53M
3.11 alpine (musl) azure-storage-file-share wheel - 1.24s 46.4M
3.11 alpine (musl) azure-storage-file-share - - 1.42s 45.3M
3.11 alpine (musl) aio wheel - 1.52s 55.4M
3.11 alpine (musl) aio - - 1.70s 54.7M
3.11 slim (glibc) azure-storage-file-share wheel 3.2s 1.07s 47M
3.11 slim (glibc) azure-storage-file-share - - 1.21s 46M
3.11 slim (glibc) aio wheel 5.3s 1.31s 58M
3.11 slim (glibc) aio - - 1.35s 57M
3.12 alpine (musl) azure-storage-file-share wheel - 1.42s 38.0M
3.12 alpine (musl) azure-storage-file-share - - 1.56s 36.8M
3.12 alpine (musl) aio wheel - 1.62s 47.0M
3.12 alpine (musl) aio - - 1.73s 46.2M
3.12 slim (glibc) azure-storage-file-share wheel 2.9s 1.37s 38M
3.12 slim (glibc) azure-storage-file-share - - 1.53s 37M
3.12 slim (glibc) aio wheel 4.2s 1.60s 49M
3.12 slim (glibc) aio - - 1.66s 49M
3.13 alpine (musl) azure-storage-file-share wheel - 1.42s 37.7M
3.13 alpine (musl) azure-storage-file-share - - 1.49s 36.4M
3.13 alpine (musl) aio wheel - 1.65s 46.7M
3.13 alpine (musl) aio - - 1.64s 45.8M
3.13 slim (glibc) azure-storage-file-share wheel 3.1s 1.31s 38M
3.13 slim (glibc) azure-storage-file-share - - 1.70s 37M
3.13 slim (glibc) aio wheel 4.6s 1.56s 49M
3.13 slim (glibc) aio - - 1.66s 48M
3.9 alpine (musl) azure-storage-file-share wheel - 0.99s 42.9M
3.9 alpine (musl) azure-storage-file-share - - 1.01s 41.8M
3.9 alpine (musl) aio wheel - 1.18s 52.0M
3.9 alpine (musl) aio - - 1.22s 51.0M
3.9 slim (glibc) azure-storage-file-share wheel 4.0s 0.90s 43M
3.9 slim (glibc) azure-storage-file-share - - 1.35s 42M
3.9 slim (glibc) aio wheel 7.4s 1.13s 54M
3.9 slim (glibc) aio - - 1.04s 53M
Imports
- ShareServiceClient wrong
from azure.storage import FileServicecorrectfrom azure.storage.fileshare import ShareServiceClient - ShareClient
from azure.storage.fileshare import ShareClient - ShareDirectoryClient
from azure.storage.fileshare import ShareDirectoryClient - ShareFileClient
from azure.storage.fileshare import ShareFileClient
Quickstart last tested: 2026-04-24
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}")