Get started with UP4W

Windows Subsystem for Linux (WSL) makes it possible to run Ubuntu on a Windows machine. Ubuntu Pro for WSL (UP4W) ensures that each new Ubuntu WSL instance that you create will automatically attach to your Ubuntu Pro subscription.

In this tutorial you will learn how to install UP4W on Windows and verify that Ubuntu WSL instances are Pro-attaching. You should then be ready for more advanced usage scenarios.

What you will do

  • Install UP4W from the Microsoft Store

  • Configure UP4W with a Pro token

  • Test automatic Pro-attachment of WSL instances

Warning

If you already have Ubuntu WSL pre-installed:

We recommend that any Ubuntu WSL installed is exported then deleted. You can then install it as described in this tutorial. At the end of the tutorial you can import and restore your data.

Read our how-to guide on backup and restore.

What you will need

  • A Windows 10 or 11 machine with a minimum of 16GB RAM and 8-core processor

  • Some familiarity with commands for the Linux shell and PowerShell

Note

WSL enables using a Linux shell and Windows PowerShell side-by-side on the same machine. In this tutorial, commands will be prefixed by a prompt that indicates the shell being used, for example:

  • PS C:\Users\me\tutorial> is a PowerShell prompt where the current working directory is C:\Users\me\tutorial.

  • u@mib:~/tutorial$ indicates a Linux shell prompt login as user “u” where the current working directory is /home/ubuntu/tutorial/

Output logs are included in this tutorial when instructive but are sometimes omitted to save space.

Set up Ubuntu WSL

Install WSL

WSL can be installed directly from the Microsoft Store.

If you already have WSL installed, with ~\.wslconfig on your system, you are advised to backup the file then remove it before continuing the tutorial.

To check if the file exists run:

PS C:\Users\me\tutorial> Test-Path -Path "~\.wslconfig"

If this returns True then the file exists and can be removed with:

PS C:\Users\me\tutorial> Remove-Item ~\.wslconfig

Install Ubuntu

Ubuntu 24.04 LTS is recommended for this tutorial and can be installed from the Microsoft Store:

Install Ubuntu 24.04 LTS from the Microsoft Store

For other installation options refer to our install Ubuntu on WSL2 guide.

At this point, running ubuntu2404.exe in PowerShell will launch an Ubuntu WSL instance and log in to its shell.

To manually associate that Ubuntu instance with a Pro subscription you could run the sudo pro attach command from within the Ubuntu instance.

This, however, would need to be repeated manually for each new instance. UP4W solves this scalability problem by automating Pro-attachment. Next, let’s take a look at how that works in practice.

Set up Ubuntu Pro for WSL

Get an Ubuntu Pro token

An active Ubuntu Pro subscription provides you with a token that can be added to the Ubuntu Pro client on WSL instances.

Your subscription token can be retrieved from the Ubuntu Pro Dashboard.

Visit the Ubuntu Pro page if you need a new subscription. The Myself option for a personal subscription is free for up to 5 machines.

Once you have a token you are ready to install UP4W.

Install and configure UP4W

Warning

The install link below will work only if you’re logged in to the Microsoft Store with an account for which access to the app has been enabled.

UP4W can be installed from this link to the Microsoft Store.

Open the application and paste the token you copied from the Ubuntu Pro dashboard:

UP4W GUI main screen

After you confirm, a status screen will appear showing that configuration is complete:

Configuration is complete

Done! You can close the UP4W window before continuing. If at any time you want to detach your Pro subscription just open the UP4W application and select Detach Ubuntu Pro.

Your Ubuntu Pro subscription is now attached to UP4W on the Windows host. UP4W will automatically forward the subscription to the Ubuntu Pro client on your Ubuntu WSL instances.

Verify Pro-attachment

All Ubuntu WSL instances will now be automatically added to your Ubuntu Pro subscription.

Open Windows PowerShell and run the following command to create a new Ubuntu 24.04 instance, entering a user and password when prompted. For quick testing, set both to u:

PS C:\Users\me\tutorial> ubuntu2404.exe

You will now be logged in to the new instance shell and can check that UP4W has Pro-attached this instance with:

u@mib:~$ pro status

The output should indicate that services like ESM are enabled, with account and subscription information also shown:

SERVICE          ENTITLED  STATUS       DESCRIPTION
esm-apps         yes       enabled      Expanded Security Maintenance for Applications
esm-infra        yes       enabled      Expanded Security Maintenance for Infrastructure

NOTICES
Operation in progress: pro attach

For a list of all Ubuntu Pro services, run 'pro status --all'
Enable services with: pro enable <service>

     Account: [email protected]
Subscription: Ubuntu Pro - free personal subscription

Packages can also be accessed from all the enabled services. Running sudo apt update will produce output like the following:

Hit:1 http://archive.ubuntu.com/ubuntu noble InRelease
Hit:2 http://ppa.launchpad.net/ubuntu-wsl-dev/ppa/ubuntu noble InRelease
Hit:3 http://security.ubuntu.com/ubuntu noble-security InRelease
Hit:4 http://archive.ubuntu.com/ubuntu noble-updates InRelease
Hit:5 http://ppa.launchpad.net/landscape/self-hosted-beta/ubuntu noble InRelease
Hit:6 https://esm.ubuntu.com/apps/ubuntu noble-apps-security InRelease
Hit:7 http://archive.ubuntu.com/ubuntu noble-backports InRelease
Hit:8 http://ppa.launchpad.net/cloud-init-dev/proposed/ubuntu noble InRelease
Hit:9 https://esm.ubuntu.com/infra/ubuntu noble-infra-security InRelease
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
All packages are up to date.

Now let’s check that another Ubuntu instance will also Pro-attach.

Install Ubuntu 22.04 LTS directly from PowerShell:

PS C:\Users\me\tutorial> wsl --install Ubuntu-22.04

Once you are in the instance shell, enter a username and password then run pro status. You should again get confirmation of successful Pro-attachment for the new instance.

If you want to uninstall UP4W after this tutorial refer to our how-to guide.

Next steps

This is only the start of what you can do with UP4W.

If you need to create and manage large numbers of Ubuntu WSL instances you will probably want to use the Windows registry. By using the Windows registry you can associate a Pro token with each new WSL instance using your organisation’s own deployment solution.

For detailed step-by-step instructions on using the Windows registry read our short guide on how to install and configure UP4W.

Landscape support is also built-in to UP4W. With a single configuration file, you can create and manage multiple WSL instances that will automatically be registered with your Landscape server:

For more information, please refer to our tutorial on how to deploy WSL instances with UP4W and Landscape.

Our documentation includes several other how-to guides for completing specific tasks, reference material describing key information relating to UP4W.