Raspberry Pi

WSL Backup and Restore

Time to take WSL (WSL2) to the next level. We assume you have installed all distros from the marketplace, tested, installed and reinstalled your favourite applications, and are looking for a way to have dedicated (own) distros for individual areas of work.

This article shows you, how to import / export and backup your own distros, which are based on marketplace templates. At the end of the day, you can run multiple instances of a given distro, with different configurations and software installed.

If you wish to get started with WSL instead, check our introduction article Windows Subsystem for Linux.

Introduction

Let's assume, that you want to extend your Debian. Use the downloaded image as a base and test platform (it's easy to reset via Add or remove programs) and that you want to setup a WSL2 Python development environment on the side. You also wish to re-install it as fast as possible, and use the environment as a base for other solutions, installed separately.

At the end of the day, you will have the following artefacts:

  • Debian (the original image, used for testing)
  • Debian Archive (a tar file, containing a vanilla base installation, used for creating and re-creating other images as a base). In the examples below, it's named debian-base.tar
  • Debian Python Environment (a fully configured Python machine, for use in Windows or Linux, running on WSL). Our name in the examples below: debian-python
  • Debian Python Archive (a tar file containing our Python environment, awaiting re-use): debian-python.tar

With the exception of Debian (original image) we keep everything separated in a dedicated WSL directory on our system. In the examples below: d:\wsl\. This directory contains our archives, and contains all custom (running) WSL images as well.

Quick Guide

For quick reference, here are the individual steps, with no explanation given. Scroll down for more details.

One time activity:

# have Debian WSL ready and initialized (reset)
#
# On the Debian terminal, install bash completion and get ready for VSCode
sudo apt update
sudo apt install bash-completion
sudo apt install wget
sudo apt install curl

# run vscode once. All requirements will be installed
code
sudo apt update && sudo apt full-upgrade

# Run the below in Powershell: You are ready for creating a backup
wsl --terminate Debian
wsl --export Debian d:\wsl\debian-base.tar
wsl --import debian-python d:\wsl\debian-python d:\wsl\debian-base.tar

# Open the below in 'debian-base' terminal:
# apply default user, as described in the footnote below, here we create the file
sudo nano etc/wsl.conf
# paste in content from below, then close and save changes. 
# Restart - your new environment is ready
# Configure Python and your development tools. Described elsewhere


# Run in PowerShell to finish installation and prepare backup for re-use
wsl --terminate debian-python
wsl --export debian-python d:\wsl\debian-python.tar

Steps to re-create a given distro:

These few steps allow you to remove the current environment, and re-create it from our tar file. Vanilla configuration ready in a minute or two!

# run in PowerShell

# remove previous installation
wsl --unregister debian-python
# import distro from backup file
wsl --import debian-python d:\wsl\debian-python d:\wsl\debian-python.tar

Tips

The above approach gives you an easy way to manage distros and your own work by preserving the intermediate steps and re-using them, when needed. Please find implementation comments in this section.

General

  • This guide does not cover the actual installation of your Python Distro. We'll come back to this in a separate guide. Instead, it focuses on easy handling of WSL2 distros
  • The guide will work on all Debian based distros. However it is specifically tailored to the state of Debian, as it was in the time of this writing. Repeating the installation elsewhere is OK, but some steps are not necessary (it won't hurt to run them anyway)
  • Base image setup
    • We install '''bash-completion''' which is not present in the current Debian
    • We'll be running some more scripts, most importantly code (visual studio code). This requires wget on first run. And, it's basically essential for any future work we'll do in our distros
    • similarly, curl is installed, as a base for many future operations

Distro Export and Import

To make a copy of a distro (i.e. for backup purposes), WSL follows the syntax:

wsl --export <Distro> <FileName>

Where:

  • Distro is the name of the Linux image (you can list images by typing wsl --list)
  • FileName is the name of file to store the image into. We add the .tar extension to clarify the format.

To import a distro to your system:

wsl --import <Distro> <InstallLocation> <FileName>

Where:

  • Distro is the new name of your Linux image
  • InstallLocation is the directory path specifying where to store your new distro
  • FileName is the backup file we have created before

Both commands allow other options, not discussed here.

Change default user

As of this writing, when you have exported and imported a distro, the default user in terminal sessions becomes root. This is incorrect for our purpose.

To change the default user, go ahead and create the configuration file etc/wsl.conf in your distro, then paste in the below:

[user]
default=your-username-here

Complete all steps by restarting your distro.

This default user setting is a Microsoft recommendation as of this writing. Better solutions are underway.

Base Image Size

The base image (tar) filesize is rather big. Make sure to compress the file for easy manipulation. For example, 7-zip will reduce the filesize by roughly 80%. Feel free to use other means of compression, such as gzip and similar.

Our WSL articles: