DEV Community

Cover image for Backing Up and Restoring WSL: How to Safeguard Your Linux Environment
devopsbg
devopsbg

Posted on

Backing Up and Restoring WSL: How to Safeguard Your Linux Environment

WSL Backup and Restore: How to Save Your Linux Environment

Working with Windows Subsystem for Linux (WSL) is like building a digital garden. You invest weeks or months setting up your environment. You install packages, configure tools, create scripts. And suddenly – a system error, corrupted hard drive, or simply the need to reinstall Windows.

All your efforts can disappear in seconds.

That's exactly why proper WSL environment backup is critically important. In this article, we'll explore how to protect your Linux environment and how to restore it when needed.

Why WSL Backup is Important

WSL is not an ordinary virtual machine. Your Linux environment is stored in a specific format in the Windows file system. During system problems, this data can be lost forever.

Imagine the following scenario: you're working on an important project, you've configured Docker containers, set up a development environment with Node.js, Python, and many other tools. Suddenly Windows gets corrupted and you need to reinstall the system.

Without backup, you lose:

  • All installed packages and configurations
  • Project files in the Linux environment
  • Personalized settings
  • SSH keys and credentials
  • Hours of setup work

WSL Backup Basics

WSL provides built-in commands for exporting and importing distributions. The process is simple, but requires planning and regularity.

What exactly are we archiving?

When we talk about archiving, we're taking a "snapshot" of the WSL distribution. This includes:

  • File system: All your files and directories
  • Installed programs: All programs and packages
  • User settings: Your configuration files
  • System settings: All WSL environment settings

With one archive, you preserve the entire distribution. This is extremely convenient. You don't need to archive each file separately.

Preparation: What We Need to Know

Before we start, here are a few important things. To archive, you need to stop the distribution. This ensures the completeness of the archive. There should be no running processes. Otherwise, the archive might be corrupted or incomplete.

The first step is to check. Verify if the WSL distribution is running. This is done with the command:

wsl --list --verbose
Enter fullscreen mode Exit fullscreen mode

You'll see a list of distributions and their status. If the status is Running, you need to stop it. This is done with the command:

wsl --terminate <distribution_name>
Enter fullscreen mode Exit fullscreen mode

For example, if the name is Ubuntu, the command would be:

wsl --terminate Ubuntu
Enter fullscreen mode Exit fullscreen mode

Then check again. Make sure the status is Stopped.

Archiving: Easy Steps

Now let's move to the essence. To archive, we'll use the wsl --export command. This command exports the distribution to a single .tar file. The TAR format is standard and very convenient for archiving.

Here's the basic syntax:

wsl --export <distribution_name> <path_to_file>
Enter fullscreen mode Exit fullscreen mode

For example, let's archive our Ubuntu distribution. We want to save it on the E: drive in a WSL_Backups folder. We want to add the date to the filename. This is good practice. This way we'll know when the archive was made. Here's the command I use:

wsl --export Ubuntu "E:\WSL_Backups\UbuntuBackup$(Get-Date -Format yyyy-MM-dd).tar"
Enter fullscreen mode Exit fullscreen mode

Let's break it down:

  • wsl --export Ubuntu: Export the distribution named Ubuntu
  • "E:\WSL_Backups\UbuntuBackup...": Specify the path and filename
  • $(Get-Date -Format yyyy-MM-dd): This code generates the current date, making filenames unique

You can execute this command from PowerShell or Command Prompt. Make sure you have write permissions. Wait for the process to complete. Depending on the distribution size, this may take time.

When the process is finished, you'll have one file. This file is the complete archive of your environment. You can copy and store it on an external drive or in the cloud, wherever is most convenient for you.

Restoration: How to Get Back in the Game

Now let's look at the reverse process. How do we restore our WSL environment? For this, we'll use the wsl --import command. This command imports a .tar file and creates a new distribution or replaces an existing one.

Here's the basic syntax:

wsl --import <new_distribution_name> <installation_path> <path_to_file>
Enter fullscreen mode Exit fullscreen mode

Let's break down this command too:

  • wsl --import <new_distribution_name>: Set a new name for your distribution, e.g., Ubuntu_Restored
  • <installation_path>: The path where you want to install WSL, e.g., C:\WSL\Ubuntu_Restored
  • <path_to_file>: Full path to your .tar file

For example, let's restore the archive we created. We want to install it on C: drive and name the distribution Ubuntu_Backup:

wsl --import Ubuntu_Backup C:\WSL\Ubuntu_Backup "E:\WSL_Backups\UbuntuBackup2025-09-02.tar"
Enter fullscreen mode Exit fullscreen mode

After executing this command, a new WSL distribution will be created. It will contain everything from your archive and be absolutely identical. You'll be able to start wsl -d Ubuntu_Backup and work as if nothing happened.

Important User Tip

When restoring, the new distribution starts as root. This can be a problem. You need to set up a default user.

To do this, you need to modify the distribution's configuration file. The file is called wsl.conf and is located in the /etc directory.

First, start the distribution as root:

wsl -d Ubuntu_Backup
Enter fullscreen mode Exit fullscreen mode

Then open the wsl.conf file:

sudo nano /etc/wsl.conf
Enter fullscreen mode Exit fullscreen mode

Add the following lines to the file:

[user]
default = your_username
Enter fullscreen mode Exit fullscreen mode

Replace your_username with your username. Save the file and exit the editor. Then close and restart:

wsl --terminate Ubuntu_Backup
wsl -d Ubuntu_Backup
Enter fullscreen mode Exit fullscreen mode

Now you'll automatically log in as your user. All your settings will be there. That's it! 🥳

Automation and Other Tips

Manual archiving is good, but why not automate it? You can create a script that you run regularly or schedule it using Windows Task Scheduler. This is a great way to ensure you always have a current archive without having to think about it.

Additional Tips:

  • Store archives elsewhere: Don't keep archives on the same drive. Use an external drive or cloud. This protects you from drive failures.

  • Archive size: The .tar file size can be large. Clean unnecessary files before archiving to save space.

  • Short and clear distribution name: Choose a short name to make it easier to work with.

Conclusion

WSL archiving is critical. It's not just an option – it's a necessity. With these simple commands, you can protect your work, save yourself a lot of headaches, and save time.

I hope this article has been helpful to you. Share it with your colleagues and friends. Let's take care of our work and protect it!

If you have questions, ask in the comments. Let's build a community where we help each other and share knowledge. Thank you! 🙏

Originally written in Bulgarian and translated to English for the dev.to community.

Read the original Bulgarian version: Бекъп и възстановяване на WSL: Как да запазите своята Linux среда

Top comments (0)