Skip to main content

AzCopy: Azure Blob Storage Management Tool

This comprehensive guide provides a quick reference for efficiently interacting with Azure Blob Storage using AzCopy, a powerful command-line utility.

Setup and Authentication​

Install AzCopy​

To install AzCopy on macOS using Homebrew:

Install AzCopy
brew install azcopy

For other operating systems, please refer to the official AzCopy installation guide.

Authenticate AzCopy​

Before using AzCopy, you need to authenticate:

Authenticate AzCopy
azcopy login

This command will open a browser window for you to log in to your Azure account. The authentication token is valid for a limited time, so you may need to re-authenticate periodically.

Core Operations​

List Blobs​

To list blobs in a container:

List Blobs
azcopy list "https://your-storage-account.blob.core.windows.net/your-container"
Sample Output
INFO: Scanning...
INFO: Failed to create OAuth token for authorization. Please use AAD credentials to access the resource.
2023/05/20 15:30:25 Failed to perform list operation
INFO: Listing finished
INFO: Elapsed time: 0.0345 seconds
note

If you see an authorization error, make sure you've logged in using azcopy login.

tip

Use the --recursive flag to list contents of all subdirectories.

Download a Blob​

To download a blob from Azure Blob Storage:

Download Blob
azcopy copy "https://your-storage-account.blob.core.windows.net/your-container/path/to/blob.ext" "/path/to/local/destination/"
Sample Output
INFO: Scanning...
INFO: Failed to create OAuth token for authorization. Please use AAD credentials to access the resource.
INFO: Uploading blob...
INFO: Blob upload successful
INFO: Elapsed time: 1.3456 seconds
INFO: Number of transfers completed: 1
INFO: Number of transfers failed: 0
INFO: Final job status: Completed

Upload a File​

To upload a file to Azure Blob Storage:

Upload File
azcopy copy "/path/to/local/file.ext" "https://your-storage-account.blob.core.windows.net/your-container/path/in/container/"
Sample Output
INFO: Scanning...
INFO: Failed to create OAuth token for authorization. Please use AAD credentials to access the resource.
INFO: Uploading blob...
INFO: Blob upload successful
INFO: Elapsed time: 2.3456 seconds
INFO: Number of transfers completed: 1
INFO: Number of transfers failed: 0
INFO: Final job status: Completed

Sync Directories​

To sync a local directory with a container:

Sync Directories
azcopy sync "/path/to/local/directory" "https://your-storage-account.blob.core.windows.net/your-container" --recursive
Sample Output
INFO: Scanning...
INFO: Failed to create OAuth token for authorization. Please use AAD credentials to access the resource.
INFO: Syncing...
INFO: Sync completed
INFO: Elapsed time: 5.6789 seconds
INFO: Number of transfers completed: 10
INFO: Number of transfers skipped: 5
INFO: Number of transfers failed: 0
INFO: Final job status: Completed
caution

The sync command can be destructive. Always use --delete-destination=false (default) to prevent accidental deletions, unless you explicitly want to delete files at the destination that don't exist at the source.

Remove a Blob​

To delete a blob from Azure Blob Storage:

Remove Blob
azcopy remove "https://your-storage-account.blob.core.windows.net/your-container/path/to/blob.ext"
Sample Output
INFO: Scanning...
INFO: Failed to create OAuth token for authorization. Please use AAD credentials to access the resource.
INFO: Removing blob...
INFO: Blob removal successful
INFO: Elapsed time: 0.5678 seconds
INFO: Number of deletions completed: 1
INFO: Number of deletions failed: 0
INFO: Final job status: Completed

Advanced Usage: SAS Tokens​

When working with Shared Access Signature (SAS) tokens, you can use them directly in your AzCopy commands instead of logging in. This is particularly useful for providing limited, temporary access to your storage resources.

List Blobs with SAS Token​

List Blobs with SAS Token
azcopy list "https://your-storage-account.blob.core.windows.net/your-container?sv=2020-08-04&ss=bfqt&srt=sco&sp=rwdlacupitfx&se=2023-06-01T12:00:00Z&st=2023-05-01T12:00:00Z&spr=https&sig=XXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Sample Output
INFO: Scanning...
file1.txt
file2.txt
folder1/
folder1/file3.txt
folder2/
folder2/file4.txt
INFO: Listing finished
INFO: Elapsed time: 0.2345 seconds

Download a Blob with SAS Token​

Download Blob with SAS Token
azcopy copy "https://your-storage-account.blob.core.windows.net/your-container/path/to/blob.ext?sv=2020-08-04&ss=bfqt&srt=sco&sp=rwdlacupitfx&se=2023-06-01T12:00:00Z&st=2023-05-01T12:00:00Z&spr=https&sig=XXXXXXXXXXXXXXXXXXXXXXXXXXXXX" "/path/to/local/destination/"
Sample Output
INFO: Scanning...
INFO: Downloading blob...
INFO: Blob download successful
INFO: Elapsed time: 1.3456 seconds
INFO: Number of transfers completed: 1
INFO: Number of transfers failed: 0
INFO: Final job status: Completed

Upload a File with SAS Token​

Upload File with SAS Token
azcopy copy "/path/to/local/file.ext" "https://your-storage-account.blob.core.windows.net/your-container/path/in/container/?sv=2020-08-04&ss=bfqt&srt=sco&sp=rwdlacupitfx&se=2023-06-01T12:00:00Z&st=2023-05-01T12:00:00Z&spr=https&sig=XXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Sample Output
INFO: Scanning...
INFO: Uploading blob...
INFO: Blob upload successful
INFO: Elapsed time: 2.3456 seconds
INFO: Number of transfers completed: 1
INFO: Number of transfers failed: 0
INFO: Final job status: Completed
warning

SAS tokens provide direct access to your storage resources. Keep them secure and avoid sharing them publicly. Use short-lived tokens and restrict permissions as much as possible.

Best Practices and Tips​

  1. Use --recursive for operations on entire directories.
  2. Simulate actions with --dry-run before making changes.
  3. Prevent accidental overwrites with --overwrite=prompt.
  4. For large transfers, use --cap-mbps to limit bandwidth usage.
  5. Enable logging with --log-level=INFO for detailed operation information.
  6. Use --exclude-pattern and --include-pattern for fine-grained control over file selection.