Skip to main content

WSL Backup, Export, and Migration

The WSL file system defaults to the system drive. This is not a problem at first, but after installing many development environments, models, caches, and datasets, it can easily become a "hidden space hog" on the C: drive.

This document mainly addresses two types of needs:

  • Creating a full backup of an existing WSL instance
  • Migrating a WSL instance from the default location to another disk

First, Distinguish the Three Actions​

Although the commands are all related to wsl --export and wsl --import, their purposes are different:

  • Backup: Export to a .tar file to preserve a snapshot
  • Recovery: Re-import the .tar as a new WSL instance
  • Migration: Export, unregister the old instance, then import to a new location

Migration is essentially "backup + delete old instance + restore at new location."

1. Confirm the Distribution You Want to Operate On​

View the current instance list in Windows PowerShell:

wsl -l -v

Focus on confirming two things:

  • The target distribution name
  • Whether it is your current default distribution

The following commands will use <DistroName> to represent this name.

2. Shut Down WSL Before Exporting​

Strictly speaking, export can sometimes be executed while the instance is running, but to minimize inconsistent states, it is recommended to shut down WSL first:

wsl --shutdown

The benefits are:

  • More consistent file system state
  • No risk of exporting while data is still being written
  • Subsequent migration steps are also clearer

3. Export a Full Backup​

Prepare a directory where you want to save the backup, for example:

New-Item -ItemType Directory -Force -Path D:\WSL\backup | Out-Null

Execute the export:

wsl --export <DistroName> D:\WSL\backup\<DistroName>-backup.tar

For example:

wsl --export Ubuntu D:\WSL\backup\Ubuntu-backup.tar

This .tar file is the full backup. As long as it exists, you can re-import it on the same machine or another machine.

4. Restore from Backup as a New Instance​

If you just want to test whether recovery is successful, the safest approach is to restore to a new name first, rather than directly overwriting the old instance.

Prepare the installation directory first:

New-Item -ItemType Directory -Force -Path D:\WSL\Ubuntu-Restore | Out-Null

Then execute the import:

wsl --import Ubuntu-Restore D:\WSL\Ubuntu-Restore D:\WSL\backup\Ubuntu-backup.tar --version 2

You will now have a new distribution Ubuntu-Restore.

Enter it for testing:

wsl -d Ubuntu-Restore

5. Migrate the Instance to Another Disk​

If your goal is not "restore an additional instance" but "move the original instance off the C: drive," the process is typically:

  1. wsl --shutdown
  2. wsl --export <DistroName> <BackupTarPath>
  3. wsl --unregister <DistroName>
  4. wsl --import <DistroName> <NewInstallPath> <BackupTarPath> --version 2

Corresponding example:

wsl --shutdown
wsl --export Ubuntu D:\WSL\backup\Ubuntu-backup.tar
wsl --unregister Ubuntu
wsl --import Ubuntu D:\WSL\Ubuntu D:\WSL\backup\Ubuntu-backup.tar --version 2

Step 3 is the most dangerous because:

wsl --unregister Ubuntu

will directly delete the currently registered instance. If you have not confirmed that the export file is usable, do not rush to do this step.

6. Restore the Default User After Import​

Many people's first reaction after migration is "why did it become root?" This is a common phenomenon after import and does not mean data is lost.

If your original user still exists but the default login user has become root, you can write wsl.conf in the imported instance:

sudo nano /etc/wsl.conf

Write the following:

[user]
default=<your_linux_user>

After saving, execute in Windows:

wsl --shutdown

Then re-enter the distribution, and the default user is usually restored.

7. How to Verify After Migration​

Don't stop just because you see "it can start." At least perform these checks:

wsl -d <DistroName> -- bash -lc "whoami && pwd && df -h /"

Then confirm inside the instance:

ls ~
echo $HOME

If you previously ran services or installed tools in WSL, you should also check:

  • Whether common directories still exist
  • Whether SSH, conda, Docker, and other configurations are still present
  • Whether project code, caches, and datasets are in expected locations

8. How to Confirm Which Disk It Is Currently On​

The location of the imported instance is determined by the installation directory specified during wsl --import.

If you migrated to:

D:\WSL\Ubuntu

Then the related virtual disk and instance data will be in this directory, no longer falling back to the original system default location.

Frequently Asked Questions​

1. Why Did the Name Change After Import​

The first argument of wsl --import is the name of the newly registered instance. Whatever you pass will appear in wsl -l -v with that name.

2. Can I Directly Overwrite Without Unregistering the Old Instance​

This is not recommended. WSL migration is better done with the approach of "export a new copy, then decide whether to delete the old instance," which makes rollback simplest.

3. What If the .tar File Is Very Large​

This is normal. A WSL backup is essentially a full file system snapshot. When doing migration, be sure to have enough space reserved, and don't start the operation when the disk has very little free space.

4. Why Restore as a New Instance First Before Deleting the Old One​

Because this is the safest approach. As long as you verify recovery is successful first, you won't discover the backup file is unusable after unregister.

A Safer Practical Order​

If the data is important, it is recommended to follow this order in actual operations:

  1. Export the backup
  2. Import as a test instance like Ubuntu-Restore
  3. Confirm you can log in and data is intact
  4. Decide whether to unregister the original instance
  5. Finally re-import with the official name to the target path

This order is a bit slower than "export then immediately unregister," but has a much higher fault tolerance.

Further Reading​