Backing Up and Restoring WSL Distributions

Your WSL distribution is more than just an operating system. It's your development environment — your shell configuration, installed tools, SSH keys, project dependencies, database setups. Rebuilding all of that from scratch takes hours, sometimes days.

And yet most people don't back up their WSL distributions. The VHDX file sitting in %LOCALAPPDATA% is silently holding everything, and one bad Windows update, a disk failure, or an accidental wsl --unregister could wipe it out.

The fix is straightforward: WSL has built-in export and import commands that create portable backup archives.

Exporting a Distribution

The wsl --export command creates a complete snapshot of your distribution's filesystem:

wsl --export Ubuntu D:\Backups\ubuntu-2026-02-21.tar

This produces an uncompressed tar archive containing every file in the distribution — installed packages, user accounts, configuration, home directories, everything.

Export Formats

WSL supports several export formats:

Uncompressed TAR (default):

wsl --export Ubuntu D:\Backups\ubuntu.tar

Fastest to create and restore, but largest file size.

Compressed TAR (gzip):

wsl --export Ubuntu D:\Backups\ubuntu.tar.gz --format tar.gz

Significantly smaller file, takes longer to create and restore.

Compressed TAR (xz):

wsl --export Ubuntu D:\Backups\ubuntu.tar.xz --format tar.xz

Smallest file size, but slowest compression. Good for archival or transferring over the network.

VHD format:

wsl --export Ubuntu D:\Backups\ubuntu.vhdx --format vhd

Copies the virtual disk directly. Fastest export, preserves everything including disk structure and default user settings. Restore is also fast since it skips tar extraction.

Which Format Should I Use?

For regular backups to a local or external drive, VHD format is usually the best choice. It's fast in both directions and preserves your default user setting. Use compressed TAR when file size matters more than speed.

Restoring from a Backup

From a TAR Archive

wsl --import Ubuntu "C:\WSL\Ubuntu" D:\Backups\ubuntu-2026-02-21.tar

The arguments are: name, install location, and backup file path.

After importing from TAR, you'll need to fix the default user since TAR imports default to root:

wsl -d Ubuntu -u root

# Add your default user to wsl.conf if not already there
grep -q "^\[user\]" /etc/wsl.conf 2>/dev/null || cat >> /etc/wsl.conf << 'EOF'
[user]
default=yourusername
EOF
exit

wsl --terminate Ubuntu
wsl -d Ubuntu
whoami

From a VHD Backup

wsl --import Ubuntu "C:\WSL\Ubuntu" D:\Backups\ubuntu.vhdx --vhd

VHD restores are faster and your default user setting is already correct — no manual fix needed.

Restoring Over an Existing Distribution

If you're restoring to replace a damaged distribution, unregister the old one first:

wsl --unregister Ubuntu
wsl --import Ubuntu "C:\WSL\Ubuntu" D:\Backups\ubuntu.vhdx --vhd

Warning: --unregister permanently deletes the distribution's virtual disk. Make sure your backup is valid before doing this.

A Simple Backup Script

Here's a PowerShell script that backs up all your distributions:

$backupDir = "D:\Backups\WSL"
$date = Get-Date -Format "yyyy-MM-dd"

# Create backup directory
New-Item -ItemType Directory -Path "$backupDir\$date" -Force | Out-Null

# Get all distributions
$distros = wsl --list --quiet | Where-Object { $_ -and $_.Trim() }

foreach ($distro in $distros) {
    $distro = $distro.Trim()
    $backupFile = "$backupDir\$date\$distro.vhdx"
    Write-Host "Backing up $distro..."
    wsl --export $distro $backupFile --format vhd
    Write-Host "  Done: $backupFile"
}

Write-Host "`nAll distributions backed up to $backupDir\$date"

Save this as backup-wsl.ps1 and run it periodically. You could schedule it with Task Scheduler for automated weekly backups.

What's Included (and What's Not)

Included in the backup:

• All installed packages and their configuration
• All user accounts and home directories
• System configuration (/etc/, services, cron jobs)
• Custom scripts and tools you've installed
• Database data files (if running databases inside WSL)
• SSH keys, GPG keys, shell configuration

NOT included:

• WSL configuration from .wslconfig (this is a Windows-side file at %USERPROFILE%\.wslconfig)
• Distribution-specific settings in the Windows Registry (default user, WSL version)
• Windows Terminal profile customizations
• Mounted Windows drives content (they're just mount points)

If you have customized .wslconfig, back that up separately:

Copy-Item "$env:USERPROFILE\.wslconfig" "D:\Backups\WSL\wslconfig-backup"

The Easy Way: WSL UI

WSL UI provides one-click export and import through the quick actions menu. Click Export on any distribution to get a save dialog with your distribution name and today's date as the default filename. Import opens a dialog where you select the tar file, enter a name, and choose an install location.

The app also tracks import/export metadata — recording when and from where each distribution was imported, so you can trace the history of your environments.

Tips

• Include the date in filenames: Ubuntu-2026-02-21.tar makes it clear when the backup was taken
• Store backups on a different drive: If your C: drive fails, backups on D: or an external drive survive
• Test your backups periodically: Import a backup under a temporary name to verify it works, then wsl --unregister the test import
• Back up before risky operations: Before major upgrades, kernel changes, or experimental tooling
• Keep at least two generations: Don't overwrite your only backup — rotate between two or three copies

Summary

Your WSL environment is worth protecting. A few minutes of backup now can save hours of rebuilding later.

Originally published at https://wsl-ui.octasoft.co.uk/blog/backing-up-and-restoring-wsl-distributions