Manage and configure instances of Ubuntu on WSL¶

This page includes guidance on managing instances of Ubuntu on WSL.

Additional resources¶

We provide a reference for instance configuration to support quick lookup of configuration methods, including: WSL Settings, .wslconfig, wsl.conf, Cloud-init, and Ubuntu Pro for WSL:

WSL instance configuration reference

Microsoft’s official documentation has general guidelines for:

Backing up an instance¶

When backing up an instance, you can export a tarball or the virtual hard disk (VHD) for the instance.

Using a VHD has the advantage of not requiring a compression/decompression step.

Using tarballs

To backup an Ubuntu-24.04 instance, first make a backup folder:

C:\Users\<username>¶

> mkdir backup

Then create a compressed version of the Ubuntu instance in that backup directory:

C:\Users\<username>¶

> wsl --export Ubuntu-24.04 .\backup\Ubuntu-24.04.tar.gz

Using VHD

To backup an Ubuntu-24.04 instance, first make a backup folder:

C:\Users\<username>¶

> mkdir backup

Then create a .vhdx of the Ubuntu instance in that backup directory:

C:\Users\<username>¶

> wsl --export Ubuntu-24.04 .\backup\Ubuntu-24.04.vhdx --format vhd

Virtual Hard Disk

To learn more about managing VHD for WSL, read Microsoft’s how to manage WSL disk space.

Removing and deleting the instance¶

Once you have created a backup of your Ubuntu instance, it is safe to remove it from WSL and delete all associated data.

Remove the instance with the following command:

> wsl --unregister Ubuntu-24.04

Restoring the backed-up instance¶

Using tarballs

To restore the Ubuntu-24.04 instance that you have previously backed up as a tarball:

C:\Users\<username>¶

> wsl --import Ubuntu-24.04 .\backup\Ubuntu2404\ .\backup\Ubuntu-24.04.tar.gz

Using VHD

To restore the Ubuntu-24.04 instance that you have previously backed up as a VHD, create a copy of the VHD:

C:\Users\<username>¶

> wsl --import Ubuntu-24.04 .\backup\Ubuntu2404\ .\backup\Ubuntu-24.04.vhdx --vhd

A quicker option is to import the already filled, ready-to-use, virtual hard drive:

C:\Users\<username>¶

wsl --import-in-place Ubuntu-24.04 .\backup\Ubuntu-24.04.vhdx

Using the restored backup¶

After restoring your backup of Ubuntu-24.04, it can be launched as normal. The instance should be restored with your previous configuration intact.

To log in as a user k, created with the original instance, run:

> wsl -d Ubuntu-24.04 -u k

Alternatively, add the following to /etc/wsl.conf in the instance:

[user]
default=k

Without specifying a user you will be logged in as the root user.

Naming instances¶

Assigning unique names to instances can be helpful if you want to install the same base distribution for different projects and/or with different configurations.

Creating duplicate instances with unique names¶

It is possible to create multiple instances from a base instance. For example, to create multiple new instances from an instance that has been backed up as a tarball:

C:\Users\<username>¶

> wsl --import ubuntu2404b .\backup\Ubuntu2404b\ .\backup\Ubuntu-24.04.tar.gz
> wsl --import ubuntu2404c .\backup\Ubuntu2404c\ .\backup\Ubuntu-24.04.tar.gz

This will create two additional instances of Ubuntu 24.04 with unique names that can be launched and configured independently.

In PowerShell, running wsl -l -v will output the new instances in your list of installed instances:

NAME            STATE         VERSION
Ubuntu-24.04    Stopped       2
ubuntu2404b     Stopped       2
ubuntu2404c     Stopped       2

To launch the first derived instance and log in as the user k run:

> wsl -d ubuntu2404b -u k

Renaming an existing instance using the registry¶

Stop all WSL instances:

> wsl --shutdown

Open the registry editor and find:

HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss

Each distribution is represented by a unique ID under Lxss.

Go to the WSL instance that you want to rename and change the value for DistributionName.

Select any ID then change the value for DistributionName to rename that instance.

To confirm that the instance has been renamed, run

> wsl -l -v

Creating a new instance with a custom name¶

The --name flag can be used with wsl.exe to customize the name of an instance during installation:

> wsl --install Ubuntu-24.04 --name UbuntuWebDev

Then launch the instance as normal:

> wsl -d UbuntuWebDev

Automatic configuration of instances¶

New instances can be configured automatically using cloud-init.

This can be used for automatic configuration of local or remote instances.

Automatic configuration of local instances¶

When adding configuration files for cloud-init, use the .cloud-init directory, which must be located in your Windows home directory.

To automatically configure an Ubuntu instance during installation, first create a .user-data file that matches the instances that will be installed and configured:

C:\Users\<user>
└── .cloud-init
    ├── Ubuntu-22.04.user-data
    └── Ubuntu-24.04.user-data

In this case, Ubuntu-22.04 and Ubuntu-24.04 will be automatically configured on installation.

You can create multiple unique cloud-init configuration setups for a single distribution (e.g., Ubuntu 24.04), as long as you are installing instances of the distribution that have been assigned unique names.

Extending the previous example, you can add instance configurations for specific projects:

C:\Users\<user>
└── .cloud-init
    ├── Ubuntu-22.04.user-data
    ├── Ubuntu-24.04.user-data
    ├── Ubuntu-web-dev.user-data
    └── Ubuntu-data-science.user-data

How to write a cloud-init configuration

For details on the contents of cloud-init configuration files, read our dedicated cloud-init guide.

Install instances of the Ubuntu-24.04 distribution that will have your unique configurations applied using the --name flag:

> wsl --install Ubuntu-24.04 --name UbuntuWebDev
> wsl --install Ubuntu-24.04 --name UbuntuDataScience

For guidance on assigning unique names to instances, go to the section on instance naming.

Automatic configuration of remote instances¶

If you centrally manage remote Pro-attached Ubuntu instances using Landscape, you can create WSL profiles to deploy to Windows machines.

These profiles are based on cloud-init.

For more detail, refer to our dedicated tutorial on Landscape deployment.

Configuration with custom images¶

If you want to control the default configurations and packages available at the distro-level, you can create a custom Ubuntu image for WSL that can be shared and distributed.

For more detail, refer to our dedicated guide on customizing an Ubuntu image.