How to use Azure File storage from Python

Tip

Try the Microsoft Azure Storage Explorer

Microsoft Azure Storage Explorer is a free, standalone app from Microsoft that enables you to work visually with Azure Storage data on Windows, macOS, and Linux.

Overview

This article will show you how to perform common scenarios using File storage. The samples are written in Python and use the Microsoft Azure Storage SDK for Python. The scenarios covered include uploading, listing, downloading, and deleting files.

What is Azure File storage?

File storage offers shared storage for applications using the standard SMB 2.1 or SMB 3.0 protocol. Microsoft Azure virtual machines and cloud services can share file data across application components via mounted shares, and on-premises applications can access file data in a share via the File storage API.

Applications running in Azure virtual machines or cloud services can mount a File storage share to access file data, just as a desktop application would mount a typical SMB share. Any number of Azure virtual machines or roles can mount and access the File storage share simultaneously.

Since a File storage share is a standard file share in Azure using the SMB protocol, applications running in Azure can access data in the share via file I/O APIs. Developers can therefore leverage their existing code and skills to migrate existing applications. IT Pros can use PowerShell cmdlets to create, mount, and manage File storage shares as part of the administration of Azure applications. This guide will show examples of both.

Common uses of File storage include:

  • Migrating on-premises applications that rely on file shares to run on Azure virtual machines or cloud services, without expensive rewrites
  • Storing shared application settings, for example in configuration files
  • Storing diagnostic data such as logs, metrics, and crash dumps in a shared location
  • Storing tools and utilities needed for developing or administering Azure virtual machines or cloud services

File storage concepts

File storage contains the following components:

files-concepts

  • Storage Account: All access to Azure Storage is done through a storage account. See Azure Storage Scalability and Performance Targets for details about storage account capacity.
  • Share: A File storage share is an SMB file share in Azure. All directories and files must be created in a parent share. An account can contain an unlimited number of shares, and a share can store an unlimited number of files, up to the 5 TB total capacity of the file share.
  • Directory: An optional hierarchy of directories.
  • File: A file in the share. A file may be up to 1 TB in size.
  • URL format: Files are addressable using the following URL format:
    https://<storage account>.file.core.windows.net/<share>/<directory/directories>/<file>

    The following example URL could be used to address one of the files in the diagram above:
    http://samples.file.core.windows.net/logs/CustomLogs/Log1.txt

For details about how to name shares, directories, and files, see Naming and Referencing Shares, Directories, Files, and Metadata.

Create an Azure storage account

The easiest way to create your first Azure storage account is by using the Azure portal. To learn more, see Create a storage account.

You can also create an Azure storage account by using Azure PowerShell, Azure CLI, or the Storage Resource Provider Client Library for .NET.

If you prefer not to create a storage account at this time, you can also use the Azure storage emulator to run and test your code in a local environment. For more information, see Use the Azure Storage Emulator for Development and Testing.

Create a share

The FileService object lets you work with shares, directories and files. The following code creates a FileService object. Add the following near the top of any Python file in which you wish to programmatically access Azure Storage.

from azure.storage.file import FileService

The following code creates a FileService object using the storage account name and account key. Replace 'myaccount' and 'mykey' with your account name and key.

file_service = **FileService** (account_name='myaccount', account_key='mykey')

In the following code example, you can use a FileService object to create the share if it doesn't exist.

file_service.create_share('myshare')

Upload a file into a share

An Azure File Storage Share contains at the very least, a root directory where files can reside. In this section, you'll learn how to upload a file from local storage onto the root directory of a share.

To create a file and upload data, use the create_file_from_path, create_file_from_stream, create_file_from_bytes or create_file_from_text methods. They are high-level methods that perform the necessary chunking when the size of the data exceeds 64 MB.

create_file_from_path uploads the contents of a file from the specified path, and create_file_from_stream uploads the contents from an already opened file/stream. create_file_from_bytes uploads an array of bytes, and create_file_from_text uploads the specified text value using the specified encoding (defaults to UTF-8).

The following example uploads the contents of the sunset.png file into the myfile file.

from azure.storage.file import ContentSettings
file_service.create_file_from_path(
    'myshare',
    None, # We want to create this blob in the root directory, so we specify None for the directory_name
    'myfile',
    'sunset.png',
    content_settings=ContentSettings(content_type='image/png'))

How to: Create a Directory

You can also organize storage by putting files inside sub-directories instead of having all of them in the root directory. The Azure file storage service allows you to create as many directories as your account will allow. The code below will create a sub-directory named sampledir under the root directory.

file_service.create_directory('myshare', 'sampledir')

How to: List files and directories in a share

To list the files and directories in a share, use the list_directories_and_files method. This method returns a generator. The following code outputs the name of each file and directory in a share to the console.

generator = file_service.list_directories_and_files('myshare')
for file_or_dir in generator:
    print(file_or_dir.name)

Download files

To download data from a file, use get_file_to_path, get_file_to_stream, get_file_to_bytes, or get_file_to_text. They are high-level methods that perform the necessary chunking when the size of the data exceeds 64 MB.

The following example demonstrates using get_file_to_path to download the contents of the myfile file and store it to the out-sunset.png file.

file_service.get_file_to_path('myshare', None, 'myfile', 'out-sunset.png')

Delete a file

Finally, to delete a file, call delete_file.

file_service.delete_file('myshare', None, 'myfile')

Next steps

Now that you've learned the basics of File storage, follow these links to learn more.