How to Backup and Restore Systems in WSL2

When using Windows Subsystem for Linux 2 (WSL2) as your development environment, it’s crucial to know how to back up and restore your WSL2 distributions. Whether you need to move your environment to a new machine or restore it after making changes, having a solid backup and restore process will save you a lot of time and effort.

In this tutorial, I’ll walk you through the steps to back up and restore your WSL2 distributions.

Step 1: Backing Up Your WSL2 Distribution

WSL2 uses virtual hard disks (.vhdx files) to store your Linux file system. However, the easiest way to back up a WSL2 distribution is by exporting the entire distribution into a tarball using the wsl command.

Here’s how you can back up your WSL2 distribution:

Open PowerShell or Command Prompt.
Run the following command to export your WSL2 distribution to a .tar file:
1 wsl --export <DistributionName> <BackupFilePath>
Replace <DistributionName> with the name of your WSL2 distribution (e.g., Ubuntu-22.04), and replace <BackupFilePath> with the path where you want to save the backup file.

Example:
1 wsl --export Ubuntu-22.04 C:\WSLBackups\UbuntuBackup.tar

This command creates a tarball of your WSL2 distribution, containing all files, packages, and configurations.

Step 2: Restoring Your WSL2 Distribution

To restore a WSL2 distribution from a backup, you can import the .tar file back into WSL. This can be done either on the same machine (if you reset WSL) or on a different machine where you want to restore your environment.

Open PowerShell or Command Prompt.
Run the following command to import your WSL2 distribution from the backup .tar file:
1 wsl --import <NewDistributionName> <InstallLocation> <BackupFilePath>
Replace <NewDistributionName> with the name you want for the restored distribution, <InstallLocation> with the folder where you want to install the distribution, and <BackupFilePath> with the path to your backup file.

Example:
1 wsl --import Ubuntu-Restored C:\WSL\RestoredDistribution C:\WSLBackups\UbuntuBackup.tar

This will restore your WSL2 distribution from the backup file to the specified installation location.

Step 3: Verifying the Restore

Once the restore is complete, you can verify the restored WSL2 distribution by listing all available distributions with the following command:

wsl --list --verbose

You should see the newly restored distribution in the list, and you can start it by simply running:

wsl -d <NewDistributionName>

Example:

wsl -d Ubuntu-Restored

Step 4: Optional - Removing Old Distributions

If you want to clean up old distributions, you can use the wsl --unregister command to remove them. Be careful, as this will delete the distribution and all its data.

wsl --unregister <DistributionName>

Example:

wsl --unregister Ubuntu-22.04

This can be useful when you want to free up space after restoring a distribution.

Final Tips

Automation: You can automate the backup process by setting up a script to regularly export your WSL2 distribution and store it in a safe location, such as an external drive or cloud storage.
Storage Location: Make sure to store your backup .tar files in a secure location, especially if they contain sensitive data.
WSL Version: Keep in mind that these steps apply to WSL2. The wsl --export and wsl --import commands are specific to WSL2 distributions.

By following these steps, you can ensure that your WSL2 environment is safely backed up and can be restored whenever needed.

References:

WSL Documentation

How to Backup and Restore Systems in WSL2