Windows Subsystem for Linux

Windows Subsystem for Linux is a feature in Windows 10 and 11 that, in essence, is a Linux system as a Windows application.

Ultramarine only supports WSL2. WSL2 is essentially a “lightweight utility virtual machine” running through Hyper-V, Microsoft’s hypervisor. This gives Ultramarine full access to the Windows filesystem, and direct hardware access, with performance similar to that of baremetal Linux.

It is possible to install and run graphical Linux applications, and even full desktop environments. We plan to make running a desktop environment through Ultramarine WSL easier in the future.

System Requirements

WSL2, and by extension Ultramarine WSL, needs the following:

  • Windows 10 (Version 2004/Build 19041), or Windows 11. IPv6 may have issues in Windows 10.
  • Hardware Virtualization enabled. All pre-installed Windows 11 computers come with Virtualization enabled.

To determine your virtualization status, look in Task Manager -> Performance tab -> CPU, and find virtualization information. You can also open a command prompt or PowerShell window and run the following command:

systeminfo.exe

Locate the ‘Hyper-V Requirements’ section, near the bottom. Within that section, locate ‘Virtualization Enabled In Firmware: yes/no.’ If yes, you are good to go. If no, you will need to enable it in your UEFI/BIOS.

Enabling Virtualization

  • Power off your device.
  • Press the power button, then press your BIOS key.
  • Locate the virtualization option. This can be in various places depending on the motherboard/manufacturer. Typically, this will be in the CPU configuration menu. Check with your manufacturer if you need help.
  • Save and exit. There will typically be a dedicated key to do this, or a select option on the main or exit page.

Hardware virtualization should now be enabled, and you can proceed to installation.

Installing Ultramarine WSL

Install using the Microsoft Store

Open the Microsoft Store, and search ‘Ultramarine Linux’ in the Microsoft Store app, or use this link

Select ‘Ultramarine Linux,’ verify the author is Fyra Labs, and then select ‘Get.‘

After this, Ultramarine WSL will appear as a Windows app. You can select ‘Open’ from the Microsoft Store window.

You’re now ready for the Post-Installation section!

Install with WinGet

Before installing with WinGet, you must install WSL itself. To do this, run the following command in an Administrator PowerShell Window or Windows Command Prompt:

wsl --install

Note — this will also install the default Ubuntu WSL distribution.

After WSL is installed, we can install Ultramarine. Open a PowerShell Window or Windows Command Prompt, and enter the following command:

winget install ultramarine

After this, Ultramarine WSL will appear as a Windows application. This will install everything needed for WSL, and Ultramarine WSL, assuming the requirements are met.

You’re now ready for the Post-Installation section!

Install from the Command Line

Before installing through the command line, you must install WSL itself. To do this, run the following command in an Administrator PowerShell Window or Windows Command Prompt:

wsl --install

Note — this will also install the default Ubuntu WSL distribution.

After WSL is installed, we can install Ultramarine. Open a PowerShell Window or Windows Command Prompt, and enter the following command:

curl https://images.fyralabs.com/images/ultramarine/41/wsl-wsl-x86_64.wsl -o ultramarine.wsl; wsl --install --from-file ultramarine.wsl

This command will download the latest available Ultramarine WSL build, output the file as ultramarine.wsl, then install ultramarine.wsl with WSL.

Be sure to replace the file name in the URL to match your architecture. If you are on x86_64, you don’t need to change anything. If you’re using AArch64 (Windows on ARM), change to wsl-wsl-aarch64.wsl.

After this, Ultramarine WSL will appear as a Windows application. This will install everything needed for WSL, and Ultramarine WSL, assuming the requirements are met.

You’re now ready for the Post-Installation section!

Post-installation

Ultramarine WSL may take a few minutes to start up for the first time, as Windows installs the required files.

Creating a User and Password

When WSL finishes starting. you will be prompted to enter a username and password. This does not need to be the same as your Windows username and password.

Updating

It is always recommended to update a fresh install. To do this, please run the following command:

sudo dnf upgrade

Setting your Default WSL Distro as Ultramarine

To change your default WSL distro to Ultramarine, run the following command:

wsl --setdefault Ultramarine

If Ultramarine is not detected, you can run the following command to list all installed WSL distros:

wsl -l

Then, replace Ultramarine in the setdefault command with the listed name.

More Information

Microsoft has vast resources about WSL, here are some helpful links:

General WSL information: https://learn.microsoft.com/en-us/windows/wsl/about

Basic WSL commands: https://learn.microsoft.com/en-us/windows/wsl/basic-commands#set-default-wsl-version

Best Practices: https://learn.microsoft.com/en-us/windows/wsl/setup/environment

Frequently Asked Questions: https://learn.microsoft.com/en-us/windows/wsl/faq

Next Up: Gaming on Ultramarine →

← Back To: Raspberry Pi