Blob Versioning in Azure Storage

How versioning works

When you enable versioning on a storage account, Azure starts tracking every state of every blob. The current blob is called the current version. Every time you overwrite or replace a blob, the old content becomes a previous version, identified by a version ID that looks like a timestamp: 2026-03-19T12:34:56.1234567Z.

When you delete a blob with versioning enabled, the blob is not truly gone. The current version is removed from the namespace (so listing the container won’t show it), but previous versions remain accessible by version ID until you delete them explicitly.

This behavior is different from soft delete. Soft delete puts a deleted blob into a hidden state and automatically removes it after a retention period. Versioning preserves every previous state indefinitely until you explicitly delete the versions or use a lifecycle policy to clean them up.

Enabling versioning

Versioning is disabled by default. You enable it at the storage account level, and it applies to all containers in that account.

# Enable blob versioning on a storage account
az storage account blob-service-properties update \
  --account-name mystorageaccount123 \
  --resource-group my-storage-rg \
  --enable-versioning true

# Confirm it's enabled
az storage account blob-service-properties show \
  --account-name mystorageaccount123 \
  --resource-group my-storage-rg \
  --query "isVersioningEnabled"

Enabling versioning only affects blobs going forward. Blobs that existed before you enabled versioning do not get retroactive version history — they become “current versions” with no prior versions.

Viewing and working with versions

# Upload an initial blob
az storage blob upload \
  --account-name mystorageaccount123 \
  --container-name documents \
  --name report.pdf \
  --file ./report-v1.pdf \
  --auth-mode login

# Overwrite it with a new version
az storage blob upload \
  --account-name mystorageaccount123 \
  --container-name documents \
  --name report.pdf \
  --file ./report-v2.pdf \
  --auth-mode login

# List all versions of the blob
az storage blob list \
  --account-name mystorageaccount123 \
  --container-name documents \
  --include v \
  --auth-mode login \
  --query "[?name=='report.pdf']" \
  --output table

The —include v flag tells the list command to include versions in the output. Each version has a versionId property you’ll use to access or restore a specific version.

# Download a specific previous version by version ID
az storage blob download \
  --account-name mystorageaccount123 \
  --container-name documents \
  --name report.pdf \
  --version-id "2026-03-19T10:00:00.0000000Z" \
  --file ./report-recovered.pdf \
  --auth-mode login

Restoring a previous version

To restore a previous version as the current version, copy the old version over the current blob:

# Get the version ID you want to restore (from the list command above)
VERSION_ID="2026-03-19T10:00:00.0000000Z"
ACCOUNT="mystorageaccount123"
CONTAINER="documents"
BLOB="report.pdf"

# Copy the old version to become the new current version
az storage blob copy start \
  --account-name $ACCOUNT \
  --destination-container $CONTAINER \
  --destination-blob $BLOB \
  --source-uri "https://$ACCOUNT.blob.core.windows.net/$CONTAINER/$BLOB?versionId=$VERSION_ID" \
  --auth-mode login

This creates a new current version with the content of the old version. The original current version becomes a previous version (not deleted). You now have both the restored state and the overwritten state in your version history.

Deleting versions to control cost

Without cleanup, versions accumulate indefinitely. A frequently updated blob in a high-traffic system can generate thousands of versions per day. Use lifecycle policies to automatically delete old versions:

{
  "rules": [
    {
      "name": "CleanupVersions",
      "enabled": true,
      "type": "Lifecycle",
      "definition": {
        "filters": {
          "blobTypes": ["blockBlob"]
        },
        "actions": {
          "version": {
            "delete": {
              "daysAfterCreationGreaterThan": 30
            }
          }
        }
      }
    }
  ]
}

This keeps previous versions for 30 days, then deletes them. The current version is never touched by the version cleanup action.

To delete a specific version manually:

az storage blob delete \
  --account-name mystorageaccount123 \
  --container-name documents \
  --name report.pdf \
  --version-id "2026-03-19T08:00:00.0000000Z" \
  --auth-mode login

Versioning and soft delete together

Soft delete and versioning are separate but complementary features. Microsoft recommends enabling both:

• Versioning protects against overwrites — you can go back to any previous state of a blob.
• Soft delete protects against container-level or accidental version deletion — deleted versions go into a recoverable state for the retention period.

# Enable soft delete for blobs with 14-day retention
az storage account blob-service-properties update \
  --account-name mystorageaccount123 \
  --resource-group my-storage-rg \
  --enable-delete-retention true \
  --delete-retention-days 14

# Enable soft delete for containers
az storage account blob-service-properties update \
  --account-name mystorageaccount123 \
  --resource-group my-storage-rg \
  --enable-container-delete-retention true \
  --container-delete-retention-days 14