Install & Compatibility
Where this runs
tested against v2.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.514s · 40MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.2s · import 0.484s · 40MB
38MB installed
● package 38MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FileService
✓ from azure.storage.file import FileService
FilePermissions
✓ from azure.storage.file import FilePermissions
Introduced in v2.1.0 for granular file/directory permissions.
This quickstart demonstrates how to initialize the `FileService` using an account name and key, then create an Azure File Share, a directory within it, and finally upload a file from a byte string. Remember to replace placeholder credentials with actual values, ideally from environment variables.
import os
from azure.storage.file import FileService
# Replace with your actual storage account name and key
# For production, use environment variables or a secure configuration management system.
ACCOUNT_NAME = os.environ.get("AZURE_STORAGE_ACCOUNT_NAME", "<YOUR_ACCOUNT_NAME>")
ACCOUNT_KEY = os.environ.get("AZURE_STORAGE_ACCOUNT_KEY", "<YOUR_ACCOUNT_KEY>")
if ACCOUNT_NAME == "<YOUR_ACCOUNT_NAME>" or ACCOUNT_KEY == "<YOUR_ACCOUNT_KEY>":
print("Please set AZURE_STORAGE_ACCOUNT_NAME and AZURE_STORAGE_ACCOUNT_KEY environment variables or replace placeholders.")
else:
try:
# Create a FileService object
file_service = FileService(account_name=ACCOUNT_NAME, account_key=ACCOUNT_KEY)
share_name = "mytestshare"
directory_name = "mydirectory"
file_name = "example.txt"
file_content = b"Hello Azure File Share from v2.x!"
# Create a share (if it doesn't exist)
print(f"Creating share: {share_name}")
file_service.create_share(share_name, fail_on_exist=False)
# Create a directory (if it doesn't exist)
print(f"Creating directory: {directory_name} in share {share_name}")
file_service.create_directory(share_name, directory_name, fail_on_exist=False)
# Upload a file from bytes
print(f"Uploading file: {file_name} to {share_name}/{directory_name}")
file_service.create_file_from_bytes(
share_name,
directory_name,
file_name,
file_content,
len(file_content)
)
print(f"Successfully uploaded '{file_name}' to Azure File Share.")
# Optional: List files in the directory
print(f"Listing files in '{share_name}/{directory_name}':")
files = file_service.list_files(share_name, directory_name)
for file in files:
print(f"- {file.name}")
# Optional: Delete the file for cleanup
# print(f"Deleting file: {file_name}")
# file_service.delete_file(share_name, directory_name, file_name)
# Optional: Delete the directory and share for cleanup
# print(f"Deleting directory: {directory_name}")
# file_service.delete_directory(share_name, directory_name)
# print(f"Deleting share: {share_name}")
# file_service.delete_share(share_name)
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingThis `azure-storage-file` library (v2.x) uses an older API style and is largely superseded by the `azure-storage-file-share` library (v12.x and above) from the `azure.storage.file` namespace. The newer library offers a more idiomatic Python API, improved error handling, and support for the latest Azure Storage features. New projects should use `azure-storage-file-share` (v12+).fixFor new projects or major updates, migrate to `azure-storage-file-share` (`pip install azure-storage-file-share`) and update your code to the new API style (e.g., `from azure.storage.file import ShareServiceClient`).
affects: < 12.0.0
deprecatedThe `azure-storage-file` package (v2.x) is effectively deprecated in favor of the newer `azure-storage-file-share` package (v12.x+). While still functional, it will receive minimal updates and new features will not be backported. Consider migration to stay current with Azure SDK best practices.fixPlan a migration path to `azure-storage-file-share` (v12.x+) for ongoing development and access to new features. Refer to Microsoft's migration guides for the Azure SDK for Python.
affects: All v2.x versions
gotchaAuthentication for this v2.x library primarily relies on shared account keys or connection strings. Direct support for Azure Active Directory (AAD) or Managed Identity (MSI) is not built into this version, requiring external mechanisms or use of the v12+ SDK for integrated AAD authentication.fixUse account name and key/connection string for authentication. For AAD/MSI, consider upgrading to `azure-storage-file-share` (v12.x+) which has integrated support, or implement custom token fetching and signing for v2.x, which is complex.
affects: All v2.x versions
gotchaWhen creating files using methods like `create_file_from_bytes`, the `length` of the file content must be explicitly and correctly provided. Mismatching the provided length with the actual content size can lead to partial uploads or corrupted files without immediate, clear error messages.fixAlways pass `len(content)` (for bytes) or `os.path.getsize(filepath)` (for local files) as the `length` parameter to ensure the file is created with the correct size on the server.
affects: All v2.x versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azure.storage.file'
The `azure-storage-file` package is not installed in your Python environment, or there's a problem with your environment's Python path.
fixInstall the package using pip: `pip install azure-storage-file==2.1.0`
AttributeError: module 'azure.storage.file' has no attribute 'ShareClient'
You are attempting to use client classes or methods from the newer `azure-storage-file-share` (v12+) library with the older `azure-storage-file` (v2.x) library installed, which has a different API design and client names.
fixIf you intend to use the newer v12+ API, uninstall `azure-storage-file` and install `azure-storage-file-share`: `pip uninstall azure-storage-file && pip install azure-storage-file-share`. Then update your code to use `from azure.storage.fileshare import ShareClient` and its corresponding methods. If you must use v2.1.0, ensure your code exclusively uses `FileService` and its methods.
ResourceNotFoundError: The specified share does not exist.
The Azure File Share, directory, or file you are trying to access does not exist, or its name is misspelled. This can also occur if a parent directory does not exist when trying to create a file within it.
fixVerify the exact name and path of the file share, directory, and file in the Azure portal. Ensure that all parent directories exist before attempting to create a file within them using `file_service.create_directory(share_name, directory_name, fail_on_exist=True)` or similar methods.
This request is not authorized to perform this operation. Status: 403 (Forbidden)
Your application lacks the necessary permissions to perform the requested operation on the Azure File Share, or the connection string/SAS token is incorrect, expired, or restricted by network firewall rules.
fixCheck the following: 1. Your storage account's connection string and account key are correct and not expired. 2. If using a Shared Access Signature (SAS) token, ensure it's valid, has the correct permissions (read, write, delete, list), and has not expired. 3. Verify that your storage account's firewall rules allow access from your client's IP address or virtual network. 4. Ensure the identity used (e.g., Managed Identity) has appropriate Azure RBAC roles, such as 'Storage File Data SMB Share Contributor' for data plane operations.
Upgrade
Version history
2.1.0latest on PyPI · released Aug 2, 2019
Audit
Dependencies
azure-storage-commonrequiredProvides common storage functionalities and utilities.