{"id":972,"library":"azure-storage-file-share","title":"Azure Storage File Share","description":"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.","status":"active","version":"12.24.0","language":"python","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-file-share","tags":["azure","storage","file","share","cloud","sdk"],"install":[{"cmd":"pip install azure-storage-file-share","lang":"bash","label":"Install stable version"},{"cmd":"pip install azure-storage-file-share[aio]","lang":"bash","label":"Install with async support"}],"dependencies":[{"reason":"Required for core Azure SDK functionality and HTTP pipeline management.","package":"azure-core","optional":false},{"reason":"Internal dependency for certain cross-service functionalities within Azure Storage SDK. Users typically do not interact with it directly when using file shares.","package":"azure-storage-blob","optional":false},{"reason":"Dependency for date/time parsing.","package":"isodate","optional":false},{"reason":"Dependency for REST client serialization/deserialization.","package":"msrest","optional":false},{"reason":"Provides backported and experimental type hints.","package":"typing-extensions","optional":false},{"reason":"Recommended for passwordless authentication using Azure Active Directory (Azure AD).","package":"azure-identity","optional":true},{"reason":"Required for asynchronous client operations when using the `azure.storage.fileshare.aio` namespace.","package":"aiohttp","optional":true}],"imports":[{"note":"The v2 SDK used a monolithic `azure.storage` package with different client classes (e.g., `FileService`). V12 uses service-specific packages and client names.","wrong":"from azure.storage import FileService","symbol":"ShareServiceClient","correct":"from azure.storage.fileshare import ShareServiceClient"},{"symbol":"ShareClient","correct":"from azure.storage.fileshare import ShareClient"},{"symbol":"ShareDirectoryClient","correct":"from azure.storage.fileshare import ShareDirectoryClient"},{"symbol":"ShareFileClient","correct":"from azure.storage.fileshare import ShareFileClient"}],"quickstart":{"code":"import os\nfrom azure.storage.fileshare import ShareServiceClient\nfrom azure.core.exceptions import ResourceNotFoundError\n\n# Retrieve the connection string from an environment variable\n# Go to Azure Portal -> Storage Accounts -> your_storage_account -> Access keys\n# Copy the 'Connection string' value\nconnection_string = os.environ.get(\"STORAGE_CONNECTION_STRING\", \"DefaultEndpointsProtocol=https;AccountName=YOUR_ACCOUNT_NAME;AccountKey=YOUR_ACCOUNT_KEY;EndpointSuffix=core.windows.net\")\n\nif \"YOUR_ACCOUNT_NAME\" in connection_string or \"YOUR_ACCOUNT_KEY\" in connection_string:\n    print(\"Please set the STORAGE_CONNECTION_STRING environment variable or replace placeholder values in the quickstart code.\")\n    exit(1)\n\ntry:\n    # Create the ShareServiceClient object from a connection string\n    service_client = ShareServiceClient.from_connection_string(connection_string)\n\n    # List shares in the storage account\n    print(\"Listing shares in the storage account:\")\n    for share in service_client.list_shares():\n        print(f\"- {share.name}\")\n\n    print(\"\\nSuccessfully listed file shares.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<12.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All v12.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All v12.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All v12.x"}],"env_vars":null,"last_verified":"2026-05-12T21:58:51.115Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"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`.","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.","error":"ModuleNotFoundError: No module named 'azure.storage'"},{"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.","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.","error":"azure.core.exceptions.ResourceNotFoundError: The specified resource does not exist"},{"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.","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.","error":"AuthenticationFailed: Server failed to authenticate the request. Make sure the value of Authorization header is formed correctly including the signature."},{"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.","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.","error":"azure.core.exceptions.ClientAuthenticationError: (MissingRequiredHeader) HeaderName: x-ms-file-request-intent"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"12.24.0","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.04,"mem_mb":16.6,"disk_size":"42.9M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.13,"mem_mb":16.4,"disk_size":"41.8M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"aio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.26,"mem_mb":19.8,"disk_size":"51.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"aio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.28,"mem_mb":19.6,"disk_size":"50.3M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.4,"import_time_s":0.78,"mem_mb":16.6,"disk_size":"43M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.18,"mem_mb":16.4,"disk_size":"42M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"aio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":6.4,"import_time_s":0.92,"mem_mb":19.8,"disk_size":"53M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"aio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.95,"mem_mb":19.6,"disk_size":"53M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.24,"mem_mb":18.9,"disk_size":"46.4M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.42,"mem_mb":18.9,"disk_size":"45.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"aio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.52,"mem_mb":22.4,"disk_size":"55.4M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"aio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.7,"mem_mb":22.3,"disk_size":"54.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.2,"import_time_s":1.07,"mem_mb":18.9,"disk_size":"47M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.21,"mem_mb":18.9,"disk_size":"46M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"aio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.3,"import_time_s":1.31,"mem_mb":22.4,"disk_size":"58M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"aio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.35,"mem_mb":22.3,"disk_size":"57M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.42,"mem_mb":18.8,"disk_size":"38.0M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.56,"mem_mb":18.8,"disk_size":"36.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"aio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.62,"mem_mb":22.2,"disk_size":"47.0M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"aio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.73,"mem_mb":22.2,"disk_size":"46.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.9,"import_time_s":1.37,"mem_mb":18.8,"disk_size":"38M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.53,"mem_mb":18.8,"disk_size":"37M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"aio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.2,"import_time_s":1.6,"mem_mb":22.2,"disk_size":"49M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"aio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.66,"mem_mb":22.2,"disk_size":"49M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.42,"mem_mb":19.7,"disk_size":"37.7M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.49,"mem_mb":19.7,"disk_size":"36.4M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"aio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.65,"mem_mb":23.2,"disk_size":"46.7M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"aio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.64,"mem_mb":23.1,"disk_size":"45.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.1,"import_time_s":1.31,"mem_mb":19.7,"disk_size":"38M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.7,"mem_mb":19.7,"disk_size":"37M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"aio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.6,"import_time_s":1.56,"mem_mb":23.2,"disk_size":"49M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"aio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.66,"mem_mb":23.1,"disk_size":"48M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.99,"mem_mb":16.3,"disk_size":"42.9M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.01,"mem_mb":16.4,"disk_size":"41.8M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"aio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.18,"mem_mb":19.6,"disk_size":"52.0M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"aio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.22,"mem_mb":19.7,"disk_size":"51.0M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4,"import_time_s":0.9,"mem_mb":16.3,"disk_size":"43M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.35,"mem_mb":16.4,"disk_size":"42M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"aio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":7.4,"import_time_s":1.13,"mem_mb":19.6,"disk_size":"54M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"aio","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.04,"mem_mb":19.7,"disk_size":"53M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}