How to use the Microsoft Linux kernel v6 on Windows Subsystem for Linux version 2 (WSL2)

Article
08/24/2023

Principal author: Nuno do Carmo

Windows Subsystem for Linux version 2 (WSL2) uses by default a long term support (lts) Linux kernel. While the current WSL2 kernel is based on a version 5.x of the Linux kernel, the latest lts version is the version 6.x.

Note

you can find additional information about the Microsoft Linux kernel on the WSL2 Kernel GitHub page.

While the kernel version 5.x could be enough for the majority of users, there's specific cases where you might need to have the latest version due to additional features your applications use.

You'll see in this guide, how-to build the Microsoft Linux kernel from the version 6.x branch on GitHub and configure WSL to use your kernel instead of the stock one.

Warning

If you have multiple distros installed, they will all use the same kernel.

Prerequisites

To follow this guide, you should have the following prerequisites installed and configured:

Updated Windows 10 or 11 machine
Windows Subsystem for Linux installed from the Microsoft App Store or with the MSIX package from GitHub
A WSL distro installed (for example: Ubuntu)
[Optional] Windows Terminal installed from the Microsoft App Store or with the MSIX package from GitHub

Note

Ubuntu is taken as the default option, however you can use another distro from the Microsoft App Store and adapt the commands described in this guide to the distro of your choice.

1 - Building the Microsoft Linux kernel v6.1.x

The first step will be to build the Microsoft Linux kernel from the version 6.1.x branch on GitHub as follows:

Open a WSL terminal window and launch the distro of your choice (for example: Ubuntu)

Clone the Microsoft Linux kernel repository from GitHub:

git clone https://github.com/microsoft/WSL2-Linux-Kernel.git --depth=1 -b linux-msft-wsl-6.1.y

Install the required packages to build the kernel:

sudo apt update && sudo apt install build-essential flex bison libssl-dev libelf-dev bc python3 pahole

Change directory to the kernel source code:
```
cd WSL2-Linux-Kernel
```

Build the kernel:

make -j$(nproc) KCONFIG_CONFIG=Microsoft/config-wsl

Install the kernel modules and headers:

sudo make modules_install headers_install

Copy the kernel image to the Windows file system:
```
cp arch/x86/boot/bzImage /mnt/c/
```
Exit the WSL terminal window

2 - Installing the Microsoft Linux kernel v6.1.x

Once the Microsoft Linux kernel is built, you can configure WSL to use it instead of the stock kernel as follows:

Create or edit the file %USERPROFILE%\.wslconfig with the following content:
```
[wsl2]
kernel=C:\\bzImage
```
Open a PowerShell terminal window as Administrator
Stop the WSL instance:
```
wsl --shutdown
```

3 - Using the Microsoft Linux kernel v6.1.x

With the new Microsoft Linux kernel v6.1.x installed and configured, you can now launch your WSL2 distro and check the kernel version as follows:

Open a WSL terminal window and launch the distro of your choice (for example: Ubuntu)
Check the kernel version:
```
uname -r
```
You should see the following output:
```
6.1.x-WSL2-Microsoft
```

Congratulations, you have now the latest Microsoft Linux kernel v6.1.x installed and configured on your WSL2 instance.

Next steps

You can learn more about the WSL2 capabilities and other configurations at the Microsoft Learn website.