Windows Subsystem for Linux (WSL) Cheat Sheet

setup.md

Install and manage WSL on specified disk

Prerequisites

1. Enable virtualization in BIOS; the setting may be called VT-x, AMD-V, SVM, or Vanderpool.
   Enable Intel VT-d or AMD IOMMU if the options are available.

2. Search for "Turn Windows features on or off", open it and in the Windows Featues window tick the box in front of Hyper-V to activate it.

3. Enable Virtual Machine Platform in the Windows Features window (Turn Windows features on or off).

4. Enable Windows Subsystem for Linux in the Windows Features window (Turn Windows features on or off).

5. Search for Windows Updates and install any new WSL updates.

6. After completion of above tasks, you may want to set a specific WSL version to avoid having to migrate later (see Setting WSL versions)

Option 1: Using Microsoft Store

1. Install an Ubuntu version from the Microsoft Store (eg. Ubuntu 22.04.1 LTS)

2. Run the distro and follow the setup.

3. Open a new CMD shell and navigate to your desired disk (eg. F:/).

   cd F:
   mkdir wsl
   cd wsl
   

4. Run wsl -l to list your registered distros.

5. Run wsl --export <distro> <target-file> to export your distro to an archive.

   wsl --export Ubuntu-22.04 ubuntu-22.04.tar
   

6. Run wsl --unregister <distro> to unregister the MSStore installation.

   wsl --unregister Ubuntu-22.04
   

   Note: You can now uninstall the MStore distribution like you would any other Windows application under Apps & Features.

7. Run wsl --import <distro> <folder> <target-file>

   wsl --import Ubuntu-22.04 ubuntu-22-04 ubuntu-22.04.tar
   

8. The newly imported instance will not inherit your previously created default user and instead use root by default. To fix, find the following key in the registry

   HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss
   

   where DistributionName == <distro> and set its DefaultUid to decimal 1000 (or hex 3e8).

9. Try WSL with wsl -d <distro>

   wsl -d Ubuntu-22.04
   

Ref. https://blog.iany.me/2020/06/move-wsl-to-another-drive/

Option 2: Using LxRunOffline

1. Install scoop by running the following command from a non-admin PowerShell

   iwr -useb get.scoop.sh | iex
   

2. Install LxRunOffline by running

   scoop bucket add extras
   scoop install lxrunoffline
   

3. Download a Linux Distro archive (see LxRunOffline/wiki for alternative downloads).

   # Ubuntu 18.04
   https://cloud-images.ubuntu.com/releases/bionic/release/ubuntu-18.04-server-cloudimg-amd64-wsl.rootfs.tar.gz
   
   # Ubuntu 20.04
   https://cloud-images.ubuntu.com/releases/focal/release/ubuntu-20.04-server-cloudimg-amd64-wsl.rootfs.tar.gz
   
   # Ubuntu 22.04
   https://cloud-images.ubuntu.com/releases/jammy/release/ubuntu-22.04-server-cloudimg-amd64-wsl.rootfs.tar.gz
   

4. Install the Linux distro under WSL with

   # Change according to your preference
   LxRunOffline i -n ubuntu22 -d "C:\wsl\ubuntu22" -f "full\path\to\.tar.gz"
   

5. Login to the distro (Eg: ubuntu22)

   wsl -d ubuntu22
   

6. Once logged in, create a new user (Eg: harry)

   adduser harry
   

7. Give the user (harry) sudo access

   usermod -aG sudo harry
   

8. To set harry as default user instead of root, run the following command from the Command Prompt (CMD)

   LxRunOffline su -n ubuntu22 -v 1000
   

Ref. https://harry.plus/blog/manage-wsl-like-a-boss-with-lxrunoffline/

Setting WSL versions

• (Global) Set the default WSL version for future distro installations:

  wsl --set-default-version <version>
  

• (Individual) Convert already installed distros to a different version:

  wsl --set-version <distro_name> <version>
  

where version is usually 1 or 2.

Setting systemd as boot process.

You will need to create/edit the wsl.conf file to ensure systemd starts up on boot.

1. Open the wsl.conf file with sudo by running sudo nano /etc/wsl.conf
2. Add the following lines to the file

   [boot]
   systemd=true
   

3. Close out of the nano editor using CTRL+O to save and CTRL+X to exit.
4. Close your WSL distro Windows and run wsl.exe --shutdown from PowerShell to restart your WSL instances.
5. Relaunch your WSL distro and check that systemd is running with the following command

   systemctl list-unit-files --type=service
   

   which should show your services’ status.

Ref. https://devblogs.microsoft.com/commandline/systemd-support-is-now-available-in-wsl/

troubleshooting.md

"Failed to retrieve available kernel versions"/"Failed to check for processor microcode upgrades"

1. Run sudo -e /etc/needrestart/needrestart.conf

2. Uncomment and change the following settings:

   $nrconf{kernelhints} = 0;
   $nrconf{ucodehints} = 0;
   

Ref. https://askubuntu.com/questions/1404129/ubuntu-22-04-lts-on-wsl-failed-to-retrieve-available-kernel-versions-failed

usb_controllers.md

Sharing locally connected USB devices to WSL2

Option 1: Using usbipd-win

https://github.com/dorssel/usbipd-win

Windows software for sharing locally connected USB devices to other machines, including Hyper-V guests and WSL 2.

Option 2: Using usbipd-win with a GUI

https://gitlab.com/alelec/wsl-usb-gui

Xbox controllers require a certain xpad driver that is not enabled by default in Microsoft's version of the linux kernel.

• Requires custom linux kernel build with the following kernel config.

Kernel-Config

https://www.kernelconfig.io/config_joystick_xpad

WIP