Quickstart: Create, download, and list blobs with Azure CLI

The Azure CLI is Azure's command-line experience for managing Azure resources. You can use it in your browser with Azure Cloud Shell. You can also install it on macOS, Linux, or Windows and run it from the command line. In this quickstart, you learn to use the Azure CLI to upload and download data to and from Azure Blob storage.

Note

The features described in this article are now available to accounts that have a hierarchical namespace. To review limitations, see the Known issues with Azure Data Lake Storage Gen2 article.

Prerequisites

To access Azure Storage, you'll need an Azure subscription. If you don't already have a subscription, create a free account before you begin.

All access to Azure Storage takes place through a storage account. For this quickstart, create a storage account using the Azure portal, Azure PowerShell, or Azure CLI. For help creating the account, see Create a storage account.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Example of Try It for Azure Cloud Shell
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Launch Cloud Shell in a new window
Select the Cloud Shell button on the top-right menu bar in the Azure portal. Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block to copy the code.

  3. Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code.

If you choose to install and use the CLI locally, this quickstart requires that you are running the Azure CLI version 2.0.4 or later. Run az --version to determine your version. If you need to install or upgrade, see Install the Azure CLI.

Create a resource group

Create an Azure resource group with the az group create command. A resource group is a logical container into which Azure resources are deployed and managed.

Remember to replace placeholder values in angle brackets with your own values:

az group create \
    --name <resource-group-name> \
    --location <location>

Create a storage account

Create a general-purpose storage account with the az storage account create command. The general-purpose storage account can be used for all four services: blobs, files, tables, and queues.

Remember to replace placeholder values in angle brackets with your own values:

az storage account create \
    --name <account-name> \
    --resource-group <resource-group-name> \
    --location <location> \
    --sku Standard_ZRS \
    --encryption blob

Specify storage account credentials

The Azure CLI needs your storage account credentials for most of the commands in this tutorial. While there are several options for doing so, one of the easiest ways to provide them is to set AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_KEY environment variables.

Note

This article shows how to set environment variables using Bash. Other environments may require syntax modifications.

First, display your storage account keys by using the az storage account keys list command. Remember to replace placeholder values in angle brackets with your own values:

az storage account keys list \
    --account-name <account-name> \
    --resource-group <resource-group-name> \
    --output table

Now, set the AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_KEY environment variables. You can do this in the Bash shell by using the export command. Remember to replace placeholder values in angle brackets with your own values:

export AZURE_STORAGE_ACCOUNT="<account-name>"
export AZURE_STORAGE_KEY="<account-key>"

For more information on how to retrieve the account access keys using the Azure portal, see Manage storage account access keys.

Create a container

Blobs are always uploaded into a container. You can organize groups of blobs similar to the way you organize your files on your computer in folders.

Create a container for storing blobs with the az storage container create command.

az storage container create --name sample-container

Upload a blob

Blob storage supports block blobs, append blobs, and page blobs. The examples in this quickstart show how to work with block blobs.

First, create a file to upload to a block blob. If you're using Azure Cloud Shell, use the following command to create a file:

vi helloworld

When the file opens, press insert. Type Hello world, then press Esc. Next, type :x, then press Enter.

In this example, you upload a blob to the container you created in the last step using the az storage blob upload command. It's not necessary to specify a file path since the file was created at the root directory:

az storage blob upload \
    --container-name sample-container \
    --name helloworld \
    --file helloworld

This operation creates the blob if it doesn't already exist, and overwrites it if it does. Upload as many files as you like before continuing.

To upload multiple files at the same time, you can use the az storage blob upload-batch command.

List the blobs in a container

List the blobs in the container with the az storage blob list command.

az storage blob list \
    --container-name sample-container \
    --output table

Download a blob

Use the az storage blob download command to download the blob you uploaded earlier.

az storage blob download \
    --container-name sample-container \
    --name helloworld \
    --file ~/destination/path/for/file

Data transfer with AzCopy

The AzCopy utility is another option for high-performance scriptable data transfer for Azure Storage. You can use AzCopy to transfer data to and from Blob, File, and Table storage.

The following example uses AzCopy to upload a file called myfile.txt to the sample-container container. Remember to replace placeholder values in angle brackets with your own values:

azcopy \
    --source /mnt/myfiles \
    --destination https://<account-name>.blob.core.windows.net/sample-container \
    --dest-key <account-key> \
    --include "myfile.txt"

Clean up resources

If you no longer need any of the resources in your resource group, including the storage account you created in this quickstart, delete the resource group with the az group delete command. Remember to replace placeholder values in angle brackets with your own values:

az group delete --name <resource-group-name>

Next steps

In this quickstart, you learned how to transfer files between a local file system and a container in Azure Blob storage. To learn more about working with blobs in Azure Storage, continue to the tutorial for working with Azure Blob storage.