{"id":5584,"library":"azure-storage-file","title":"Azure Storage File Client Library (v2.x)","description":"The `azure-storage-file` library provides client-side support for interacting with Azure File Shares, enabling operations such as creating shares, directories, and files, as well as managing file content. This is the v2.x series of the client library, which adheres to an older API design. The current version is 2.1.0, and its release cadence has significantly slowed, with development efforts now focused on the newer v12+ `azure-storage-file-share` library.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-storage-python","tags":["azure","storage","file storage","cloud","deprecated","legacy"],"install":[{"cmd":"pip install azure-storage-file","lang":"bash","label":"Install `azure-storage-file`"}],"dependencies":[{"reason":"Provides common storage functionalities and utilities.","package":"azure-storage-common","optional":false}],"imports":[{"symbol":"FileService","correct":"from azure.storage.file import FileService"},{"note":"Introduced in v2.1.0 for granular file/directory permissions.","symbol":"FilePermissions","correct":"from azure.storage.file import FilePermissions"}],"quickstart":{"code":"import os\nfrom azure.storage.file import FileService\n\n# Replace with your actual storage account name and key\n# For production, use environment variables or a secure configuration management system.\nACCOUNT_NAME = os.environ.get(\"AZURE_STORAGE_ACCOUNT_NAME\", \"\")\nACCOUNT_KEY = os.environ.get(\"AZURE_STORAGE_ACCOUNT_KEY\", \"\")\n\nif ACCOUNT_NAME == \"\" or ACCOUNT_KEY == \"\":\n print(\"Please set AZURE_STORAGE_ACCOUNT_NAME and AZURE_STORAGE_ACCOUNT_KEY environment variables or replace placeholders.\")\nelse:\n try:\n # Create a FileService object\n file_service = FileService(account_name=ACCOUNT_NAME, account_key=ACCOUNT_KEY)\n\n share_name = \"mytestshare\"\n directory_name = \"mydirectory\"\n file_name = \"example.txt\"\n file_content = b\"Hello Azure File Share from v2.x!\"\n\n # Create a share (if it doesn't exist)\n print(f\"Creating share: {share_name}\")\n file_service.create_share(share_name, fail_on_exist=False)\n\n # Create a directory (if it doesn't exist)\n print(f\"Creating directory: {directory_name} in share {share_name}\")\n file_service.create_directory(share_name, directory_name, fail_on_exist=False)\n\n # Upload a file from bytes\n print(f\"Uploading file: {file_name} to {share_name}/{directory_name}\")\n file_service.create_file_from_bytes(\n share_name,\n directory_name,\n file_name,\n file_content,\n len(file_content)\n )\n\n print(f\"Successfully uploaded '{file_name}' to Azure File Share.\")\n\n # Optional: List files in the directory\n print(f\"Listing files in '{share_name}/{directory_name}':\")\n files = file_service.list_files(share_name, directory_name)\n for file in files:\n print(f\"- {file.name}\")\n\n # Optional: Delete the file for cleanup\n # print(f\"Deleting file: {file_name}\")\n # file_service.delete_file(share_name, directory_name, file_name)\n\n # Optional: Delete the directory and share for cleanup\n # print(f\"Deleting directory: {directory_name}\")\n # file_service.delete_directory(share_name, directory_name)\n # print(f\"Deleting share: {share_name}\")\n # file_service.delete_share(share_name)\n\n except Exception as e:\n print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"For 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`).","message":"This `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+).","severity":"breaking","affected_versions":"< 12.0.0"},{"fix":"Plan 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.","message":"The `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.","severity":"deprecated","affected_versions":"All v2.x versions"},{"fix":"Use 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.","message":"Authentication 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.","severity":"gotcha","affected_versions":"All v2.x versions"},{"fix":"Always 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.","message":"When 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.","severity":"gotcha","affected_versions":"All v2.x versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}