How To Use AzCopy - Azure Lessons

A manufacturing company I worked with backed up its file server by dragging folders into a browser window. It worked for the first 20 GB. Then a 400 GB engineering share timed out three nights in a row, nobody knew which files had made it, and the person who ran the job kept a SAS token in a shared spreadsheet.

We replaced the whole routine with a single command-line tool and a scheduled script. Learning how to use AzCopy took the team about an hour, and the nightly job has run without drama since. AzCopy is a free Microsoft command-line utility that moves data to, from, and between Azure storage accounts.

This guide shows you how to install AzCopy, sign in safely, upload, download, sync, and automate transfers. You will also learn the permissions, performance settings, and troubleshooting steps that keep transfers fast, cheap, and secure.

What AzCopy Is and When to Use It

AzCopy v10 is the currently supported version. It runs on supported versions of Windows, Linux, and macOS. It can copy data from a local machine to Azure, from Azure back to a local machine, and from one storage account to another. It works with Azure Blob Storage and Azure Files, and with Data Lake Storage accounts.

Choose AzCopy when you want a scriptable, resumable, high-speed transfer. A few cases where another tool fits better:

Occasional manual uploads: Azure Storage Explorer gives you a graphical interface. It uses AzCopy under the hood for its transfers.
Large migrations: Microsoft recommends Azure Storage Mover for high-scale migrations over 1 TB. See the comparison of Azure Storage Mover vs. AzCopy and the overview of Azure Storage Mover.
Offline bulk transfer: When your internet link is too slow, a physical device such as Azure Data Box can be faster.

AzCopy does not support transfers where the source or destination is changing while the copy runs. Schedule jobs when the data is quiet, or copy from a snapshot.

Pro Tip: In my experience, teams pick AzCopy for the speed and keep it for the scripting. Once a transfer is a text file you can review, you can put it in source control and audit it.

Install AzCopy and Prepare Your Storage

Linux users can install AzCopy with a package manager. On other systems, you download a portable binary and unzip it. On Windows, many admins use winget:

winget install Microsoft.Azure.AZCopy.10
azcopy --version

The first command installs AzCopy v10, and the second prints the installed version. If you downloaded the zip instead, add its folder to your system path so you can type azcopy from any directory. For a full walkthrough, see the guide to install AzCopy.

Now create a lab environment. A resource group is a logical container that groups related Azure resources. See how to create a resource group in Azure if you want the portal steps.

az group create \
  --name rg-azcopy-lab \
  --location eastus \
  --tags owner=it-team purpose=azcopy-demo

This creates rg-azcopy-lab in East US. The tags record the owner and purpose, so cost reviews are easier later. Read more about Azure tags.

az storage account create \
  --name <storage-account-name> \
  --resource-group rg-azcopy-lab \
  --location eastus \
  --sku Standard_LRS \
  --kind StorageV2 \
  --allow-blob-public-access false \
  --min-tls-version TLS1_2

This creates a general-purpose storage account. --allow-blob-public-access false blocks anonymous access, and --min-tls-version TLS1_2 rejects older encryption. Standard_LRS keeps three copies in one datacenter, which is fine for a lab but weak for important data. See the walkthrough to create Azure Blob Storage for more options.

az storage container create \
  --name backups \
  --account-name <storage-account-name> \
  --auth-mode login

This creates a container named backups. The --auth-mode login option uses your Microsoft Entra ID sign-in instead of an account key.

Pro Tip: I always create a separate container per workload, such as backups and exports. It lets me scope permissions and lifecycle rules to each job.

Authorize AzCopy the Safe Way

Being the owner of a storage account does not give you data permissions automatically. You must authorize AzCopy with either Microsoft Entra ID or a shared access signature (SAS) token.

Option 1: Microsoft Entra ID (Recommended)

With Entra ID, you sign in once and AzCopy reuses the credential. You do not append a SAS token to every command. Your identity needs a data role on the storage account:

Downloads need Storage Blob Data Reader.
Uploads need Storage Blob Data Contributor or Storage Blob Data Owner.

Role assignments can take up to five minutes to propagate. Learn the basics of Azure RBAC, which grants permissions through roles instead of broad admin rights.

az role assignment create \
  --assignee <entra-group-object-id> \
  --role "Storage Blob Data Contributor" \
  --scope /subscriptions/<subscription-id>/resourceGroups/rg-azcopy-lab/providers/Microsoft.Storage/storageAccounts/<storage-account-name>

This gives an Entra group upload and download rights, scoped to a single storage account. Use groups so you can add and remove people without editing role assignments.

Then sign in:

azcopy login --tenant-id "<tenant-id>"
azcopy login status

azcopy login opens a browser sign-in and stores an encrypted token using your operating system’s secret store. If your Linux system has no keyring, the command cannot save the token. The --tenant-id option helps when your account belongs to more than one directory. azcopy login status confirms who you are signed in as.

Already signed in with Azure CLI? AzCopy can reuse that session. Set AZCOPY_AUTO_LOGIN_TYPE=AZCLI and AZCOPY_TENANT_ID.

Option 2: SAS Token (Short Jobs Only)

A SAS token is a signed string you append to the storage URL. It works, but it expires, is hard to rotate, and grants direct access if it leaks. Follow the guide to generate a SAS token for Azure Storage if you need one, and give it the shortest expiry and fewest permissions possible. Never paste SAS tokens or storage account keys into scripts, spreadsheets, or chat.

Pro Tip: I once found a never-expiring SAS URL in a team wiki. We rotated the storage key to kill it, and three production jobs broke at once. That is why I now start every project with Entra ID and role assignments.

How to Use AzCopy: Core Commands

The general format is azcopy [command] [arguments] --[flag-name]=[flag-value]. Quote your paths. Use single quotes in all shells except cmd.exe, where you should use double quotes.

Upload Files and Folders

azcopy copy '/data/engineering' 'https://<storage-account-name>.blob.core.windows.net/backups' --recursive

This uploads the engineering folder and everything in it to the backups container. --recursive includes subfolders. Without it, AzCopy copies only files at the top level.

To upload only a folder’s contents without the folder itself, use a wildcard:

azcopy copy '/data/engineering/*' 'https://<storage-account-name>.blob.core.windows.net/backups/engineering' --recursive

For a basic portal and code-based comparison, see how to upload and download files in Azure Blob Storage.

Download Files and Folders

azcopy copy 'https://<storage-account-name>.blob.core.windows.net/backups/engineering' '/restore' --recursive

This downloads the folder to a local directory called /restore. For single files, see how to download a file from Azure Blob Storage.

Copy Between Storage Accounts

azcopy copy 'https://<source-account>.blob.core.windows.net/backups' 'https://<destination-account>.blob.core.windows.net/backups-copy' --recursive

This is a server-to-server copy. Data moves directly between storage servers, so it does not pass through your computer. You can raise AZCOPY_CONCURRENCY_VALUE above 1000 for these jobs because your machine does little of the work.

Filter What You Copy

azcopy copy '/data/reports' 'https://<storage-account-name>.blob.core.windows.net/backups/reports' --recursive --include-pattern '*.pdf;*.xlsx'

--include-pattern copies only matching file names. --exclude-pattern skips them. These options match file names, not paths. To limit by folder, use --include-path. To copy files changed after a certain time, use --include-after with an ISO 8601 date such as 2026-10-01T00:00:00Z.

Set an Access Tier While Uploading

azcopy copy '/data/old-projects' 'https://<storage-account-name>.blob.core.windows.net/archive' --recursive --block-blob-tier Cool

--block-blob-tier sets the tier on upload, and it accepts None, Hot, Cool, or Archive. Choose carefully, because cooler tiers charge early deletion fees. See the Azure storage account tier comparison and the Azure Blob Storage cost guide before archiving anything.

Pro Tip: I run every new copy command on a small test folder first. A wrong destination path creates a mess that is tedious to clean up in a container with thousands of blobs.

Sync Folders Without Re-Copying Everything

azcopy copy transfers whatever you point it at. azcopy sync compares the source and destination and moves only the differences. Sync is a better fit for recurring backups.

azcopy sync '/data/engineering' 'https://<storage-account-name>.blob.core.windows.net/backups/engineering'

By default, sync compares file names and last-modified times, and it copies subfolders because recursion is on by default. The file is skipped if the destination copy is newer.

Preview Before You Delete

By default, sync does not delete anything at the destination. The --delete-destination flag changes that. It accepts true, false, or prompt.

azcopy sync '/data/engineering' 'https://<storage-account-name>.blob.core.windows.net/backups/engineering' --delete-destination=true --dry-run

--dry-run prints the paths that would be copied or removed, but it does not change any data. Warning: --delete-destination=true permanently removes blobs that no longer exist at the source. Always run a dry run first, and enable soft delete on the storage account so you can recover from mistakes. Learn more about protecting storage accounts.

Automate AzCopy with a Managed Identity

For scheduled jobs, don’t use your own login or a long-lived SAS token. Use a managed identity, which lets an Azure resource authenticate without a stored secret. Read what a managed identity in Azure is.

Here is the scenario. A Linux VM named vm-file-backup hosts exported files, and it should push them to storage every night.

az vm identity assign \
  --resource-group <resource-group-name> \
  --name vm-file-backup

This turns on a system-assigned identity for the VM. Now grant that identity upload rights, scoped to the storage account only:

PRINCIPAL_ID=$(az vm show \
  --resource-group <resource-group-name> \
  --name vm-file-backup \
  --query identity.principalId --output tsv)

az role assignment create \
  --assignee-object-id "$PRINCIPAL_ID" \
  --assignee-principal-type ServicePrincipal \
  --role "Storage Blob Data Contributor" \
  --scope /subscriptions/<subscription-id>/resourceGroups/rg-azcopy-lab/providers/Microsoft.Storage/storageAccounts/<storage-account-name>

The first command reads the identity’s object ID and saves it in a variable. The second assigns the role. The VM can now write blobs, and nothing else.

Create the backup script on the VM at /opt/scripts/nightly-sync.sh:

#!/bin/bash
export AZCOPY_AUTO_LOGIN_TYPE=MSI
export AZCOPY_LOG_LOCATION=/var/log/azcopy
export AZCOPY_JOB_PLAN_LOCATION=/var/lib/azcopy

azcopy sync '/data/exports' \
  'https://<storage-account-name>.blob.core.windows.net/backups/exports' \
  --log-level ERROR

if [ $? -ne 0 ]; then
  echo "AzCopy sync failed at $(date)" >> /var/log/azcopy/failures.log
fi

Here is what the script does:

AZCOPY_AUTO_LOGIN_TYPE=MSI tells AzCopy to authenticate with the VM’s managed identity, so no secret is stored. You can use azcopy login --identity for the same result.
AZCOPY_LOG_LOCATION and AZCOPY_JOB_PLAN_LOCATION move logs and job plan files off the default drive, which prevents a full disk.
--log-level ERROR logs only failures, which improves performance.
The if check reads the exit code. A non-zero value means the job failed, so you can alert someone.

Schedule it with cron at 2 a.m.:

0 2 * * * /opt/scripts/nightly-sync.sh

On Windows, put the command in a PowerShell script and run it with Task Scheduler. For a secure setup, avoid saving secrets in the script. If you must store a credential, keep it in Azure Key Vault. See how Azure Key Vault works.

Pro Tip: I make every scheduled job write its exit code to a log and send an alert on failure. A backup job that fails silently is worse than no backup, because everyone assumes it works.

Speed Up Transfers

AzCopy tunes itself, but you can improve it. These settings come from Microsoft’s performance guidance:

Benchmark first. azcopy benchmark uploads generated test data and reports bottlenecks. It deletes the test data afterward.
Raise concurrency. Set AZCOPY_CONCURRENCY_VALUE or use AUTO to let AzCopy tune it. Don’t set it so high that the machine slows down.
Keep jobs smaller. Keep each job under 10 million files. Jobs above 50 million files can perform poorly because of tracking overhead, so split them with include or exclude patterns.
Reduce logging. Use --log-level ERROR.
Turn off length checking for tiny files. Setting --check-length=false can help when transferring huge numbers of small files, but you lose a safety check.
Limit bandwidth. --cap-mbps caps upload and download speed, which keeps backups from choking your office network. It does not apply to account-to-account copies.
Control memory. AZCOPY_BUFFER_GB sets how much memory AzCopy can use for buffers.
Run one instance per client. AzCopy performs best alone on a machine. For more parallelism, use several clients.

Place the machine running AzCopy close to the data. A VM in the same region as the storage account avoids internet egress and gives lower latency.

Pro Tip: I always run a benchmark from the machine that will run the job, not my laptop. The result decides whether we need a bigger VM or a faster network link.

Secure and Monitor Your Transfers

AzCopy sends data over HTTPS, but access control and network design matter just as much.

Block public exposure. Keep anonymous blob access disabled. See Azure storage account public access and this checklist on how to secure an Azure storage account.

Use private connectivity when needed. For sensitive data, a private endpoint gives the storage account a private IP address inside your virtual network. Follow how to create a private endpoint for a storage account. If you disable public access afterward, AzCopy must run from inside that network or a connected one.

Warning: turning off public network access will break any client outside the network, so test first.

Apply least privilege. Give uploaders Contributor, restorers Reader, and nobody Owner unless they need it. Test with a non-administrator account. A reader-only user should be able to download but not upload or delete.

Monitor and log. Azure Monitor collects metrics and logs from your storage account. Learn what Azure Monitor does. Alert on a sudden jump in egress or delete operations. On the AzCopy side, check job history:

azcopy jobs list
azcopy jobs show <job-id> --with-status=Failed

azcopy jobs list shows previous jobs. azcopy jobs show with --with-status=Failed lists only failed transfers, which is a fast way to find what to retry. To restart an interrupted job, run azcopy jobs resume <job-id>. If the job used a SAS token, supply the token again with --source-sas or --destination-sas, because AzCopy does not store it.

Control costs. Transfers create billable operations, and data leaving Azure incurs egress charges. Create a budget with alerts using Azure budget alerts, and keep storage and compute in the same region.

Pro Tip: In my experience, one alert on “delete operations above normal” catches both a runaway sync and a compromised credential. Add it the same day you enable --delete-destination.

Troubleshoot Common AzCopy Errors

Problem	Likely cause	Fix
`AuthorizationPermissionMismatch` (403)	Missing data role, wrong scope, or role not propagated	Assign the right Storage Blob Data role, wait up to five minutes, and sign in again
`AuthenticationFailed`	Expired SAS token or wrong credentials	Generate a new token or refresh the service principal secret
Server failed to authenticate	Clock skew, or a SAS with the wrong permissions	Fix system time and recreate the SAS with the needed permissions
Connection refused or 403 from firewall	Storage firewall or private endpoint blocks your IP	Add your IP rule, or run AzCopy from inside the network
`azcopy: command not found`	AzCopy is not on the path	Add its folder to PATH, or run it from the folder
`azcopy login` fails on Linux	No secret store or keyring available	Use environment-variable login, a managed identity, or a service principal
Sync deleted files unexpectedly	`--delete-destination=true` without a dry run	Restore with soft delete, and always preview first
Slow transfer of small files	Too many transactions	Zip small files, raise concurrency, and use `--check-length=false`
Job stalls or fails midway	Network drop or source changed during copy	Run `azcopy jobs resume`, and avoid changing source files mid-job

Also remember that AzCopy has no rename command. To rename a blob, copy it to a new name and delete the old one.

If a transfer succeeds but you cannot see the files, confirm the container name and virtual folder path. Blob Storage has no true folders, only name prefixes, so a typo creates a new “folder.”

Pro Tip: When a 403 appears, I check three things in order: the role assignment scope, the storage firewall, and the clock on the machine. That order has fixed nearly every case I have seen.

Frequently Asked Questions

What is AzCopy used for?

AzCopy is a command-line tool for copying data to, from, and between Azure storage accounts. People use it for uploads, downloads, backups, migrations, and keeping folders in sync. It supports Blob Storage and Azure Files.

What is the difference between azcopy copy and azcopy sync?

copy transfers everything you point it at, while sync compares both sides and moves only new or changed files. Sync is better for recurring backups, and copy is faster for one-time transfers. Sync never deletes destination files unless you add --delete-destination.

How do I authenticate AzCopy without a SAS token?

Run azcopy login for interactive use, or azcopy login --identity on an Azure VM with a managed identity. For automation, you can also use a service principal. Your identity needs a data role such as Storage Blob Data Contributor.

Does AzCopy overwrite existing files?

Yes, copy overwrites existing files at the destination by default. Use --overwrite=false to prevent that, or --overwrite=ifSourceNewer to replace only older files. Sync skips files when the destination copy is newer.

Can I resume a failed AzCopy transfer?

Yes. Run azcopy jobs list to find the job ID, then azcopy jobs resume <job-id>. If you used a SAS token, pass it again because AzCopy doesn’t save it.

You learned how to install AzCopy, authorize it with Microsoft Entra ID, and use copy, sync, and automation to move Azure Storage data safely. The most important rule is to use identity-based access with least privilege and to preview every sync with a dry run before you allow deletions. I hope you found this article helpful.