WSL2 Backup and Restore: Export Safely and Verify Recovery

Back up and restore WSL2: prove the restore before replacing the original

Use wsl --export to export a distribution’s filesystem, then wsl --import under a new name to test the backup. Keep the original distribution until the restored copy passes your actual file and application checks. A tar listing or the existence of /home alone does not prove that a development environment or database is recoverable.

A distribution export is not a Windows system backup and not a snapshot of running process memory. Mounted Windows drives, Windows-side WSL settings, scheduled tasks, and data stored in other distributions need their own backup plan.

Establish what belongs to the distribution

In PowerShell, list the installed distributions:

wsl --list --verbose

Use the actual target name in subsequent commands. Inside that distribution, identify project directories, database locations, and mounted paths. Files under /mnt/c normally belong to the Windows drive, not to the distribution’s root filesystem. Docker Desktop storage can belong to a separate managed environment; do not assume that exporting your ordinary Ubuntu distribution captures every Docker image and volume.

Back up %UserProfile%\.wslconfig separately if it matters to the environment. Preserve the distribution’s /etc/wsl.conf as part of its filesystem, but recognise that registration and Windows account context are separate. SSH keys and other secrets inside the filesystem also make the export sensitive; protect the backup accordingly.

Quiesce applications before export

Save work and shut down applications cleanly. For a database, use its supported backup or shutdown procedure. Terminating a distribution forcibly is not the same as asking every database to complete a clean checkpoint.

After those application steps, stop the intended distribution:

wsl --terminate Ubuntu

This stops its running work. Do not schedule it unexpectedly during someone’s active session. Exporting a live, changing filesystem should not be advertised as an atomic application-consistent snapshot. A successful command exit can coexist with files captured in an unsuitable state for a running application’s restore.

Export to a correctly formed Windows path

Use Join-Path and quote arguments rather than assembling ambiguous paths with missing separators. This PowerShell example produces an uncompressed tar export with a unique timestamp:

$DistroName = 'Ubuntu'
$BackupRoot = Join-Path $env:USERPROFILE 'WSL-Backups'
$Stamp = Get-Date -Format 'yyyyMMdd-HHmmss-fff'
$BackupFile = Join-Path $BackupRoot "$DistroName-$Stamp.tar"
New-Item -ItemType Directory -Path $BackupRoot -Force | Out-Null

wsl --export $DistroName $BackupFile
$ExportExit = $LASTEXITCODE
if ($ExportExit -ne 0) {
    throw "WSL export failed with exit code $ExportExit."
}
if (-not (Test-Path -LiteralPath $BackupFile -PathType Leaf)) {
    throw 'The export did not produce the expected file.'
}
if ((Get-Item -LiteralPath $BackupFile).Length -le 0) {
    throw 'The export file is empty.'
}
Get-FileHash -LiteralPath $BackupFile -Algorithm SHA256

The hash supports later integrity comparison. It does not prove that the archive contains the right data or that an application will run after restoration. Record the distribution, WSL version, export time, application shutdown steps, file size, and hash alongside the backup.

Duration and size depend on the data and environment. This guide does not present an invented completion time or a sample console log as a measurement from your machine. Check available space before export, retain the actual exit code, and inspect the exact error on failure.

Test import under a new name

Choose a new registration name and a dedicated empty installation directory. The following example assumes the preceding $BackupFile still identifies the export:

$TestName = 'Ubuntu-RestoreCheck'
$TestLocation = Join-Path $env:USERPROFILE 'WSL\Ubuntu-RestoreCheck'
wsl --list --verbose

# Run only after confirming the name is unused and the location is suitable.
wsl --import $TestName $TestLocation $BackupFile --version 2
if ($LASTEXITCODE -ne 0) {
    throw 'The test import failed.'
}
wsl --list --verbose
wsl -d $TestName -- cat /etc/os-release
wsl -d $TestName -- ls /home

Those checks establish that the import can launch and expose basic files. Continue with important content hashes, permissions, user accounts, package versions, and the actual project or application operation you need. For a database, test the supported restore and a meaningful query, not just the presence of its directory.

Avoid starting a restored application in a way that sends emails, triggers jobs, or writes to the same external production services as the original. The restore test should establish recoverability under controlled conditions.

Configure the imported user’s default correctly

An imported distribution may start as root unless its default-user configuration establishes another account. The vendor launcher command for a Store-installed Ubuntu distribution is not a general way to configure an arbitrarily named import.

Launch the imported distribution as root when needed:

wsl -d Ubuntu-RestoreCheck -u root

Inside Linux, verify the existing account with getent passwd yourname. Merge this into /etc/wsl.conf, preserving other sections:

[user]
default=yourname

Use an actual existing Linux account. Stop and relaunch that distribution to apply the setting, then verify with id and pwd. Current WSL versions can offer additional management commands; use the installed version’s supported command reference rather than assuming every machine supports the same option.

Archive listing is useful, but it is not a restore

For a plain tar export, use tar -tf with a suitable path. Do not force gzip handling with -z merely because the filename ends in .tar. Read the entire archive when testing readability and capture the result; piping the first few names through head cannot validate the whole file.

Then import and verify the important application. The difference is practical: an archive may list successfully while missing a mounted project directory, a separate Docker environment, or a usable database backup. Your test should catch those omissions.

Automate the verified process, including its failure behaviour

Run a scheduled backup under the Windows account that owns the intended distributions. Choose an explicit distribution allowlist rather than automatically stopping every environment, including managed ones. Use unique filenames, per-distribution exit checks, an append-only run log, and a final failing exit when any required export fails.

Do not delete the last known good backups merely because the calendar reached a retention cutoff. Separate export success, integrity checks, restore verification, and retention. A new failed export must not trigger the destruction of your only recoverable generation. Keep an off-machine copy if the backup is meant to survive disk loss.

Test the scheduled task itself under its actual account and conditions. A successful manual run does not establish that the task can see the distributions, access the destination, or run at the intended time. Measure its real result rather than waiting ten seconds and assuming a multi-gigabyte export has completed.

Migrate only after the restore check passes

Copy the export and its integrity record to the destination machine through a protected channel or storage location appropriate for its contents. Compare the hash after transfer. Install compatible WSL tooling, import under a chosen name, configure the user and resources, and repeat the file and application checks.

Architecture, WSL features, external mounts, and application dependencies can matter. A tar filesystem export should not be described as universally portable between every Windows machine with no version or architecture considerations.

Only decide whether to remove the original after the new environment is verified and the retention plan is clear. wsl --unregister permanently deletes the named distribution’s data; it is not part of the initial restore test. If cleaning up a disposable test import, verify the exact test name before deletion.

Questions readers often ask

Does export include my Windows Documents folder?

No, not merely because it is accessible under /mnt/c. Back up Windows-side data separately.

Does finding my username under /home prove the backup is good?

No. Test important files and application operations in the imported copy.

Why does the imported copy start as root?

Check its default-user configuration. For an import, merge an appropriate [user] setting into /etc/wsl.conf or use the installed tooling’s supported management command.

Is an export on the same disk enough for disaster recovery?

It can help with some rollback scenarios but will not survive that disk’s loss. Keep a protected independent copy and a tested restore procedure.

Primary references: Microsoft’s WSL command guide and WSL configuration reference.