Back up WSL and restore under a new name without removing Ubuntu

After setting up a development environment in Ubuntu on WSL, you may want a way back before an update or configuration change. Copying your source code alone does not preserve the installed tools and Linux settings.

WSL can export a Linux distribution to a tar file with wsl --export and create a distribution from it with wsl --import. The steps below keep the original environment, restore the archive under a different name, and check that the files and Linux user you need are available.

Identify the distribution to back up

Run the following in PowerShell on Windows. These examples assume Windows 11 with WSL and a WSL 2 distribution already installed.

wsl --version
wsl --list --verbose

The NAME column contains the name to use for the backup. Ubuntu-24.04 and Ubuntu are different registration names, so use the exact name in your own output. A 2 in the VERSION column means WSL 2; it is separate from the installed WSL package version, such as 3.x.

The tar archive contains the selected distribution’s Linux filesystem, including home directory files and Linux configuration. Back up Windows files accessed through /mnt/c or /mnt/d separately on Windows. Save the Windows user folder’s .wslconfig separately too if you want to retain settings such as memory limits.

Choose backup and restore locations

This example uses Ubuntu-24.04 as the original distribution and Ubuntu-BackupCheck for the restored copy. Adapt the drive and folders to your computer. Choose a new registration name that is not already in use.

$Distro = 'Ubuntu-24.04'
$BackupDir = 'D:\WSL-Backup\before-update-01'
$Backup = Join-Path $BackupDir 'ubuntu-backup.tar'
$Restored = 'Ubuntu-BackupCheck'
$RestoreDir = 'D:\WSL-Restore\Ubuntu-BackupCheck'

New-Item -ItemType Directory -Path $BackupDir -ErrorAction Stop | Out-Null
if (Test-Path -LiteralPath $RestoreDir) {
    throw 'Choose a new folder for the restored distribution.'
}

The backup folder is new as well, to avoid overwriting an earlier backup. If it exists, New-Item stops; choose another folder. You need enough free space for both the archive and the restored filesystem. Leave room based on the original environment’s usage rather than estimating the restored size from the tar file alone.

SSH keys and credentials stored inside Linux may be included in the archive. Keep it in a location with restricted access, away from public folders and shared links. After verifying restoration, keeping another copy on separate storage can help protect against a failed PC.

Save work and stop the selected distribution

Save changes in your editor and shut down servers or databases inside Linux using their normal procedures. Use the database product’s backup procedure where needed. Forced termination alone does not guarantee that an application has finished its work cleanly.

wsl --terminate $Distro
if ($LASTEXITCODE -ne 0) {
    throw 'WSL termination failed. Check the displayed error.'
}

--terminate stops the named distribution. --shutdown affects other running WSL environments too, so naming the distribution keeps this operation focused. Until export completes, avoid reopening the selected environment through a terminal or integrated application.

Export and check the tar file

Export the stopped distribution from the same PowerShell session. Large environments can take time. Wait for the command to finish before copying the archive or using it for import.

wsl --export $Distro $Backup
if ($LASTEXITCODE -ne 0) {
    throw 'Exporting the backup failed.'
}

$Archive = Get-Item -LiteralPath $Backup -ErrorAction Stop
if ($Archive.Length -eq 0) {
    throw 'The backup file is empty.'
}
$Archive | Select-Object Name, Length
Get-FileHash -LiteralPath $Backup -Algorithm SHA256 |
    Format-List Algorithm, Hash

An exit code of 0 and a file Length greater than 0 are initial checks. A SHA256 digest is useful for comparing a file before and after copying it to other storage. Size and hash alone do not show that the data you need can be restored, so continue with a separate import.

If export fails, inspect the distribution name, destination, free space, and error message. You can investigate without deleting the original environment.

Restore under a new name and keep the original

List the registered names again and check that $Restored is unused. Then create a new WSL 2 environment from the tar archive.

wsl --list --verbose
wsl --import $Restored $RestoreDir $Backup --version 2
if ($LASTEXITCODE -ne 0) {
    throw 'Importing under the new name failed.'
}
wsl --list --verbose

When both the original name and Ubuntu-BackupCheck appear in the list, you can address the two environments separately. Unregistering the original is unnecessary for this backup and restore check. wsl --unregister deletes the selected distribution’s data; do not insert it into the backup procedure.

Import fails if the registration name is already in use. Choose another name and installation folder instead of removing the existing environment. If the archive cannot be found, check the file path stored in $Backup.

Check files and the Linux user

Start the restored environment by name. Checking its initial user helps you interpret file ownership and home directory paths.

wsl -d $Restored --exec whoami
wsl -d $Restored --exec ls /home

An imported distribution starts as root unless a default user is configured. Check any default-user setting in its Linux /etc/wsl.conf. Starting as root does not by itself mean the original user or files are missing.

If your original Linux user was demo, you can select it as follows. Replace this example with your own existing Linux username.

$LinuxUser = 'demo'
wsl -d $Restored -u $LinuxUser --exec id
wsl -d $Restored -u $LinuxUser

In the Linux terminal that opens, inspect projects and configuration files in the home directory. Compare representative files with the original, check their owners, and try the development tools you need. This provides more useful evidence than creating an archive alone.

Before starting a server in the restored copy, consider port conflicts with the original and connections to external services. The backup may retain application configuration and credentials, so restoration checks do not require running jobs that write to production services.

When finished, close the Linux terminal with exit, then stop only the restored distribution from PowerShell. You can retain both the tar archive and the original environment.

wsl --terminate $Restored

Keep a backup for the next change

Once the required files and user are available in the restored copy, record the backup date and original distribution name in the filename or a storage note. Files created after that backup will not be present in the earlier archive, so make new backups as the environment changes.

Windows files used by a container still need their own backup. For how a bind-mounted workspace relates to Windows storage, see WSL containers and saving files to Windows.

References

• Microsoft Learn: basic WSL commands
• Microsoft Learn: import a Linux distribution from tar
• Microsoft Learn: advanced WSL configuration