How to Move WSL2 File System to Another Drive: A Step-by-Step Guide

Moving your WSL2 file system to another drive can be a smart move for several reasons. It helps free up space on your primary drive, especially if it’s a smaller SSD, and can improve overall system performance by reducing the load on your main drive. This process involves exporting your current WSL2 instance and importing it to a new location, ensuring you maintain all your configurations and data.

Prerequisites

To move your WSL2 file system to another drive, follow these prerequisites:

1. Software and Tools:

   • Windows 10 or 11 with the latest updates.
   • PowerShell for executing commands.
   • WSL 2 installed and configured.

2. Permissions:

   • Administrator rights on your Windows machine.
   • Read/Write access to the target drive.

3. Preparatory Steps:

   • Check WSL version and distribution:

     wsl --list --verbose
     

   • Identify your WSL username:

     whoami
     

   • Shut down WSL to avoid data corruption:

     wsl --shutdown
     

   • Create a backup of your WSL distribution:

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

   • Unregister the current WSL distribution:

     wsl --unregister <DistroName>
     

   • Import the WSL distribution to the new drive:

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

   • Set the default user (if needed):

     cd $env:USERPROFILE\AppData\Local\Microsoft\WindowsApps
     <DistroName> config --default-user <YourUsername>
     

Ensure you replace <DistroName> and <YourUsername> with your actual distribution name and username.

Step-by-Step Guide

Here’s a detailed, step-by-step guide to move your WSL2 file system to another drive:

Step 1: Check Existing WSL2 Installations

Open PowerShell and list your current WSL2 distributions:

wsl --list --verbose

!Step 1

Step 2: Stop the WSL2 Distribution

If the distribution you want to move is running, stop it:

wsl --terminate <DistroName>

Replace <DistroName> with the name of your distribution (e.g., Ubuntu-20.04).

Step 3: Export the WSL2 Distribution

Export your WSL2 distribution to a file. For example, to export Ubuntu-20.04 to D:\wsl_export\ubuntu.tar:

wsl --export Ubuntu-20.04 D:\wsl_export\ubuntu.tar

!Step 3

Step 4: Unregister the WSL2 Distribution

Unregister the distribution from WSL2:

wsl --unregister Ubuntu-20.04

!Step 4

Step 5: Import the WSL2 Distribution to the New Drive

Create a directory on the new drive where you want to move the distribution. For example, D:\wsl_import\ubuntu:

mkdir D:\wsl_import\ubuntu

Then import the distribution:

wsl --import Ubuntu-20.04 D:\wsl_import\ubuntu D:\wsl_export\ubuntu.tar

!Step 5

Step 6: Set Default User (Optional)

If needed, set the default user for the distribution:

ubuntu2004.exe config --default-user <YourUsername>

Replace <YourUsername> with your actual username.

Step 7: Verify the Move

Start the distribution to ensure everything works correctly:

wsl -d Ubuntu-20.04

!Step 7

That’s it! Your WSL2 file system should now be moved to the new drive.

Verifying the Move

Here are the steps to verify that your WSL2 file system has been successfully moved to another drive:

1. Check WSL2 Installation:

   • Run wsl --list --verbose to ensure your distribution is listed and running from the new location.

2. Verify File Integrity:

   • Compare the size of the original and moved .tar files using Get-ChildItem -Path <path_to_tar> | fl @{Label="SizeGb"; Expression={$_.Length / 1Gb}} in PowerShell.
   • Use checksums (e.g., Get-FileHash <path_to_tar>) to ensure the files are identical.

3. Check System Recognition:

   • Ensure the new path is correctly set in the registry under HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss\{UUID}\BasePath.
   • Run wsl --shutdown and then wsl to restart and verify the system recognizes the new location.

4. Test Functionality:

   • Open your WSL2 distribution and run a few commands to ensure everything works as expected.

These steps should help you confirm that the move was successful and that your WSL2 environment is functioning correctly on the new drive.

Troubleshooting

Here are some troubleshooting tips for common issues when moving the WSL2 file system to another drive:

1. Permission Errors:

   • Run as Administrator: Ensure you’re running PowerShell or Command Prompt as an administrator.
   • Check File Permissions: Verify that the destination drive and folders have the correct permissions set. Use icacls to adjust permissions if needed.

2. Missing Files:

   • Verify Export: Ensure the export command (wsl --export <distro> <path>) completes successfully and the .tar file is intact.
   • Check Paths: Double-check the paths used during the import process (wsl --import <distro> <path> <tar-file>).

3. Registry Issues:

   • Update Registry: If manually moving files, update the registry key HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss\<UUID>\BasePath to point to the new location.

4. WSL Not Starting:

   • Restart WSL: Use wsl --shutdown to stop all instances and then restart your WSL distribution.
   • Check Logs: Look at the Windows Event Viewer for any related error messages.

5. Disk Space Issues:

   • Optimize VHD: Use Optimize-VHD -Path <path-to-vhd> -Mode Full to reduce the size of the VHD file.

Moving Your WSL2 File System to Another Drive

To move your WSL2 file system to another drive, you’ll need to export it from its current location, import it into the new location, and then verify that everything is working correctly. This process can be beneficial for several reasons: it allows you to free up space on your original drive, improve performance by moving the file system to a faster drive, or even upgrade to a larger storage capacity.

Exporting Your WSL2 Distribution

First, export your WSL2 distribution using the command `wsl –export `.

wsl --export <distro> <path>

This will create a `.tar` file containing your entire file system. Next, import this file into the new location using `wsl –import `.

wsl --import <distro> <path> <tar-file>

Make sure to replace `` with your distribution name, `` with the path to the new drive, and `` with the path to the exported `.tar` file.

Verifying Everything is Working Correctly

After importing the file system, verify that everything is working correctly by checking the WSL2 installation, verifying file integrity, checking system recognition, and testing functionality. You can do this by running `wsl –list –verbose`, comparing the size of the original and moved `.tar` files using PowerShell, ensuring the new path is correctly set in the registry, and opening your WSL2 distribution to run a few commands.

wsl --list --verbose

Troubleshooting Tips

If you encounter any issues during this process, there are several troubleshooting tips you can follow. For permission errors, make sure you’re running as an administrator and check file permissions on the destination drive. If files are missing, verify that the export command completed successfully and double-check the paths used during import. Registry issues can be resolved by updating the registry key to point to the new location, while WSL not starting can be fixed by restarting WSL or checking logs for error messages. Finally, disk space issues can be addressed by optimizing the VHD file using PowerShell.

Conclusion

By following these steps carefully and troubleshooting any issues that arise, you should be able to successfully move your WSL2 file system to another drive and enjoy the benefits of improved performance, increased storage capacity, or simply freeing up space on your original drive.