Back Up and Restore a WSL 2 Distribution on Windows 11 24H2

A WSL distribution can hold source code, package state, databases, shell configuration, SSH material, and other files that are not necessarily covered by ordinary Windows folder backup tools. Microsoft recommends the built-in wsl --export and wsl --import commands for backing up or moving a complete distribution. This procedure adds two useful safeguards: a SHA-256 checksum for the archive and an isolated restore drill that leaves the original distribution registered.

Scope

Platform: Windows

Version: Windows 11 version 24H2

Guest distribution: Ubuntu 24.04 LTS running as WSL 2 and registered as Ubuntu-24.04.

Shell: Windows PowerShell 5.1 or PowerShell 7, with every block below entered in the same window so its variables remain available.

The procedure creates a timestamped TAR archive in the current Windows user’s WSL-Backups folder, writes a SHA-256 sidecar file, inspects the archive listing, and imports a temporary copy named Ubuntu-24.04-RestoreCheck. It does not replace or unregister the original distribution. Microsoft documents TAR as the default export format and permits an imported distribution to use a new name and installation directory in its WSL command reference.

Prerequisites

You need an existing WSL 2 distribution whose exact registered name is Ubuntu-24.04, enough free Windows storage for a second copy of its data, and permission to stop its running processes. Microsoft’s WSL FAQ warns that a complete transfer can require substantial disk space. A backup should ultimately be copied to storage that is not dependent on the same physical disk as the source.

Close editors, databases, containers, and other programs that are actively writing inside the distribution. The export command creates a distribution snapshot, but stopping the instance first gives applications a clear boundary before the archive is made. Confirm the registered name and WSL generation:

wsl.exe --list --verbose
wsl.exe --version

The Ubuntu-24.04 row should report WSL version 2. If the distribution has a different name, do not continue with these commands until $Distro is deliberately changed to the exact value shown by wsl.exe --list --verbose. Distribution names are identifiers, so a near match is not sufficient.

Procedure

First, define concrete names, refuse to continue if the expected distribution is absent, create the backup directory, and stop only that distribution. Microsoft’s command reference says --terminate stops the named distribution; it is narrower than --shutdown, which stops every running distribution and the WSL 2 utility virtual machine.

$Distro = "Ubuntu-24.04"
$Stamp = Get-Date -Format "yyyyMMdd-HHmmss"
$BackupRoot = Join-Path $env:USERPROFILE "WSL-Backups"
$BackupFile = Join-Path $BackupRoot "Ubuntu-24.04-$Stamp.tar"
$HashFile = "$BackupFile.sha256.txt"

$InstalledDistros = wsl.exe --list --quiet
if ($InstalledDistros -notcontains $Distro) {
    throw "The WSL distribution Ubuntu-24.04 is not registered."
}

New-Item -ItemType Directory -Path $BackupRoot -Force | Out-Null
wsl.exe --terminate $Distro
if ($LASTEXITCODE -ne 0) { throw "WSL could not terminate Ubuntu-24.04." }

Export the stopped distribution. The default output is a TAR file, as specified by Microsoft. An independent Windows Central walkthrough corroborates the export-and-import workflow and the need to use the exact registered distribution name.

wsl.exe --export $Distro $BackupFile
if ($LASTEXITCODE -ne 0) { throw "The WSL export failed." }
if (-not (Test-Path -LiteralPath $BackupFile)) { throw "The backup archive was not created." }

Record a SHA-256 checksum and inspect, without extracting, the first ten archive entries. Get-FileHash computes a content hash and defaults to SHA-256; the algorithm is stated explicitly here for clarity. Windows 11 includes tar, and Microsoft’s Windows TAR documentation documents -tf for listing archive contents. A visible listing is stronger evidence than the filename alone, although it is not a substitute for importing the archive.

$BackupHash = (Get-FileHash -LiteralPath $BackupFile -Algorithm SHA256).Hash
Set-Content -LiteralPath $HashFile -Value $BackupHash -Encoding ascii
Get-Item -LiteralPath $BackupFile, $HashFile | Select-Object FullName, Length, LastWriteTime
tar.exe -tf $BackupFile | Select-Object -First 10
if ($LASTEXITCODE -ne 0) { throw "Windows tar could not list the backup archive." }

Copy both the TAR file and its .sha256.txt sidecar to the same protected backup destination. Keeping the sidecar beside the archive makes it possible to detect an accidental change before restoration. A matching checksum shows that the bytes are unchanged from the moment the sidecar was created; it does not prove that every application inside the distribution will start correctly.

Next, import the archive under an isolated name. The guard clauses stop rather than overwrite an existing registration or directory. The --version 2 option makes the intended WSL generation explicit.

$RestoreName = "Ubuntu-24.04-RestoreCheck"
$RestoreRoot = Join-Path $env:LOCALAPPDATA "WSL\Ubuntu-24.04-RestoreCheck"

$InstalledDistros = wsl.exe --list --quiet
if ($InstalledDistros -contains $RestoreName) {
    throw "Ubuntu-24.04-RestoreCheck is already registered."
}
if (Test-Path -LiteralPath $RestoreRoot) {
    throw "The restore directory already exists."
}

New-Item -ItemType Directory -Path $RestoreRoot | Out-Null
wsl.exe --import $RestoreName $RestoreRoot $BackupFile --version 2
if ($LASTEXITCODE -ne 0) { throw "The isolated WSL import failed." }

An imported distribution may initially open as root because Store-distribution launcher settings do not apply to imported instances. That behavior does not invalidate the archive. If the restored copy will be retained for normal use, configure its default user separately through /etc/wsl.conf after confirming that the intended account exists.

Verification and expected outcome

Recompute the archive checksum, compare it with the saved value, list the registered distributions, and ask the restored instance to identify its operating system. These checks keep the original and restored registrations visibly separate.

$ExpectedHash = (Get-Content -LiteralPath $HashFile -Raw).Trim()
$ActualHash = (Get-FileHash -LiteralPath $BackupFile -Algorithm SHA256).Hash
$ExpectedHash -eq $ActualHash
wsl.exe --list --verbose
wsl.exe --distribution $RestoreName -- cat /etc/os-release

Expected outcome: PowerShell prints True for the checksum comparison; wsl.exe --list --verbose includes both Ubuntu-24.04 and Ubuntu-24.04-RestoreCheck, with the restored row showing version 2; and /etc/os-release identifies Ubuntu 24.04 LTS. Application-specific data should then be checked from inside the restored copy before the archive is accepted as a usable recovery point.

For a development distribution, sensible checks include confirming that expected project directories exist, opening important configuration files, and using each application’s own integrity or recovery command. A WSL import confirms that the archive can be registered and started; it cannot establish that an application was quiescent at export time or that an external dependency remains available.

Cautions

wsl.exe --terminate Ubuntu-24.04 immediately stops processes in that distribution. Save work and stop databases or other write-heavy services cleanly before reaching that command. Do not export while a package upgrade, database migration, or filesystem-intensive job is underway.

Treat the TAR file as sensitive. It can contain private source code, shell history, environment files, browser or package credentials, SSH keys, database content, and personal data. Store it with access controls and encryption appropriate to its contents. Do not upload it to an untrusted archive-inspection service.

Plan for more free space than the visible used size inside Linux: the TAR archive and restored virtual disk coexist during this drill. Do not unregister the original distribution merely because the restored name appears in the list. First inspect important data and applications in the isolated copy.

A checksum detects later byte changes only when the sidecar itself is trusted and retained separately or protected with the archive. It does not provide authenticity against an attacker who can replace both files, and it does not replace multiple backup generations or an off-device copy.

Rollback or removal

If the restored copy was created only for verification, remove that copy after closing anything using it. Microsoft’s WSL reference warns that --unregister permanently deletes the named distribution’s data, settings, and installed software. Read $RestoreName before continuing and never substitute the original Ubuntu-24.04 name.

$RestoreName
$RestoreRoot
wsl.exe --terminate $RestoreName
wsl.exe --unregister $RestoreName
if ($LASTEXITCODE -ne 0) { throw "The temporary restored distribution was not unregistered." }
if (Test-Path -LiteralPath $RestoreRoot) {
    Remove-Item -LiteralPath $RestoreRoot -Recurse -Force
}
wsl.exe --list --verbose

The final list should no longer contain Ubuntu-24.04-RestoreCheck, while the original Ubuntu-24.04 remains registered. Keep the TAR archive and checksum for recovery, or remove them later only after another verified backup generation exists. If the import failed before registration completed, check wsl.exe --list --verbose first; delete only the concrete $RestoreRoot directory shown above after confirming that no registered distribution uses it.