Azure Storage File Share SDK for Python
Manage SMB file shares for cloud-native and lift-and-shift scenarios.
Installation
pip install azure-storage-file-share
Environment Variables
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...
Or
AZURE_STORAGE_ACCOUNT_URL=https://<account>.file.core.windows.net
Authentication
Connection String
from azure.storage.fileshare import ShareServiceClient
service = ShareServiceClient.from_connection_string( os.environ["AZURE_STORAGE_CONNECTION_STRING"] )
Entra ID
from azure.storage.fileshare import ShareServiceClient from azure.identity import DefaultAzureCredential
service = ShareServiceClient( account_url=os.environ["AZURE_STORAGE_ACCOUNT_URL"], credential=DefaultAzureCredential() )
Share Operations
Create Share
share = service.create_share("my-share")
List Shares
for share in service.list_shares(): print(f"{share.name}: {share.quota} GB")
Get Share Client
share_client = service.get_share_client("my-share")
Delete Share
service.delete_share("my-share")
Directory Operations
Create Directory
share_client = service.get_share_client("my-share") share_client.create_directory("my-directory")
Nested directory
share_client.create_directory("my-directory/sub-directory")
List Directories and Files
directory_client = share_client.get_directory_client("my-directory")
for item in directory_client.list_directories_and_files(): if item["is_directory"]: print(f"[DIR] {item['name']}") else: print(f"[FILE] {item['name']} ({item['size']} bytes)")
Delete Directory
share_client.delete_directory("my-directory")
File Operations
Upload File
file_client = share_client.get_file_client("my-directory/file.txt")
From string
file_client.upload_file("Hello, World!")
From file
with open("local-file.txt", "rb") as f: file_client.upload_file(f)
From bytes
file_client.upload_file(b"Binary content")
Download File
file_client = share_client.get_file_client("my-directory/file.txt")
To bytes
data = file_client.download_file().readall()
To file
with open("downloaded.txt", "wb") as f: data = file_client.download_file() data.readinto(f)
Stream chunks
download = file_client.download_file() for chunk in download.chunks(): process(chunk)
Get File Properties
properties = file_client.get_file_properties() print(f"Size: {properties.size}") print(f"Content type: {properties.content_settings.content_type}") print(f"Last modified: {properties.last_modified}")
Delete File
file_client.delete_file()
Copy File
source_url = "https://account.file.core.windows.net/share/source.txt" dest_client = share_client.get_file_client("destination.txt") dest_client.start_copy_from_url(source_url)
Range Operations
Upload Range
Upload to specific range
file_client.upload_range(data=b"content", offset=0, length=7)
Download Range
Download specific range
download = file_client.download_file(offset=0, length=100) data = download.readall()
Snapshot Operations
Create Snapshot
snapshot = share_client.create_snapshot() print(f"Snapshot: {snapshot['snapshot']}")
Access Snapshot
snapshot_client = service.get_share_client( "my-share", snapshot=snapshot["snapshot"] )
Async Client
from azure.storage.fileshare.aio import ShareServiceClient from azure.identity.aio import DefaultAzureCredential
async def upload_file(): credential = DefaultAzureCredential() service = ShareServiceClient(account_url, credential=credential)
share = service.get_share_client("my-share")
file_client = share.get_file_client("test.txt")
await file_client.upload_file("Hello!")
await service.close()
await credential.close()
Client Types
Client Purpose
ShareServiceClient
Account-level operations
ShareClient
Share operations
ShareDirectoryClient
Directory operations
ShareFileClient
File operations
Best Practices
-
Use connection string for simplest setup
-
Use Entra ID for production with RBAC
-
Stream large files using chunks() to avoid memory issues
-
Create snapshots before major changes
-
Set quotas to prevent unexpected storage costs
-
Use ranges for partial file updates
-
Close async clients explicitly