Develop for Azure Files with Python


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.

About this tutorial

This tutorial will demonstrate the basics of using Python to develop applications or services that use Azure Files to store file data. In this tutorial, we will create a simple console application and show how to perform basic actions with Python and Azure Files:

  • Create Azure File shares
  • Create directories
  • Enumerate files and directories in an Azure File share
  • Upload, download, and delete a file

Because Azure Files may be accessed over SMB, it is possible to write simple applications that access the Azure File share using the standard Python I/O classes and functions. This article will describe how to write applications that use the Azure Storage Python SDK, which uses the Azure Files REST API to talk to Azure Files.

Download and Install Azure Storage SDK for Python

Azure Storage SDK for Python requires Python 2.7, 3.3, 3.4, 3.5, or 3.6, and comes in 4 different packages: azure-storage-blob, azure-storage-file, azure-storage-table and azure-storage-queue. In this tutorial we are going to use azure-storage-file package.

Install via PyPi

To install via the Python Package Index (PyPI), type:

pip install azure-storage-file

If you are upgrading from the Azure Storage SDK for Python version 0.36 or earlier, you will first need to uninstall using pip uninstall azure-storage as we are no longer releasing the Storage SDK for Python in a single package.

For alternative installation methods, visit the Azure Storage SDK for Python on Github.

Set up your application to use Azure Files

Add the following near the top of any Python source file in which you wish to programmatically access Azure Storage.

from import FileService

Set up a connection to Azure Files

The FileService object lets you work with shares, directories and files. 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')

Create an Azure File share

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


Create a directory

You can also organize storage by putting files inside sub-directories instead of having all of them in the root directory. Azure Files 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')

Enumerate files and directories in an Azure File 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:

Upload a file

Azure File 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 import ContentSettings
    None, # We want to create this blob in the root directory, so we specify None for the directory_name

Download a file

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')

Create share snapshot (preview)

You can create a point in time copy of your entire file share.

snapshot = file_service.snapshot_share(share_name)
snapshot_id = snapshot.snapshot

Create share snapshot with metadata

metadata = {"foo": "bar"}
snapshot = file_service.snapshot_share(share_name, metadata=metadata)

List shares and snapshots

You can list all the snapshots for a particular share.

shares = list(file_service.list_shares(include_snapshots=True))

Browse share snapshot

You can browse content of each share snapshot to retrieve files and directories from that point in time.

directories_and_files = list(file_service.list_directories_and_files(share_name, snapshot=snapshot_id))

Get file from share snapshot

You can download a file from a share snapshot for your restore scenario.

with open(FILE_PATH, 'wb') as stream:
    file = file_service.get_file_to_stream(share_name, directory_name, file_name, stream, snapshot=snapshot_id)

Delete a single share snapshot

You can delete a single share snapshot.

file_service.delete_share(share_name, snapshot=snapshot_id)

Delete share when share snapshots exist

A share that contains snapshots cannot be deleted unless all the snapshots are deleted first.

file_service.delete_share(share_name, delete_snapshots=DeleteSnapshot.Include)

Next steps

Now that you've learned how to manipulate Azure Files with Python, follow these links to learn more.