The Windows Subsystem for Linux (WSL2) has transformed Windows 11 into a powerful platform for developers, providing a genuine Linux environment natively. However, by default, WSL2 uses a generic Microsoft-provided Linux kernel. While this standard kernel is highly optimised for general workloads, developers working on specialised tasks—such as embedded systems development, custom device drivers, or specific networking protocols—often require a custom Linux kernel.
Configuring WSL2 to boot with a custom kernel allows you to enable specific kernel modules, test bleeding-edge features, or minimise the system footprint by stripping out unnecessary components. This guide explains the complete workflow for compiling a custom Linux kernel and configuring Windows 11 to utilise it within your WSL2 instances.
Prerequisites for Kernel Compilation
Before beginning the compilation process, ensure your system meets the necessary requirements. You will need a functioning WSL2 environment running a Debian-based distribution (such as Ubuntu) to compile the kernel. Additionally, ensure you have sufficient disk space, as kernel source trees and build artefacts can consume several gigabytes.
First, update your package repositories and install the essential build dependencies required for compiling a Linux kernel:
sudo apt update && sudo apt install build-essential flex bison libssl-dev libelf-dev bc python3 dwarves
Acquiring the WSL2 Kernel Source Code
Microsoft maintains a dedicated fork of the Linux kernel specifically patched for WSL2 compatibility. While you can technically use the mainline Linux kernel, utilising Microsoft’s branch ensures seamless integration with the Windows host, particularly concerning memory management and hypervisor integration.
Clone the official WSL2 kernel repository from GitHub. To save time and bandwidth, perform a shallow clone of the specific branch you wish to compile:
git clone --depth 1 -b linux-msft-wsl-6.1.y https://github.com/microsoft/WSL2-Linux-Kernel.git
cd WSL2-Linux-Kernel
Configuring the Kernel Options
The kernel configuration defines which features and modules are compiled into the final image. Microsoft provides a default configuration tailored for WSL2, which serves as an excellent starting point.
Copy the default configuration to your build environment:
make KCONFIG_CONFIG=Microsoft/config-wsl x86_64_defconfig
Next, open the interactive configuration menu to customise the kernel options. This interface allows you to enable or disable specific kernel features depending on your development requirements:
make menuconfig
Navigate through the menus to select the required modules. For example, if you require specific CAN bus networking protocols for embedded development, enable them under the ‘Networking support’ section. Once your modifications are complete, save the configuration and exit the interface.
Compiling the Custom Linux Kernel
With the configuration finalised, you can begin the compilation process. To significantly reduce the build time, utilise the -j flag to instruct the compiler to run multiple parallel jobs. A good rule of thumb is to set this number to match the number of logical CPU cores available on your system.
make -j$(nproc)
The compilation process may take several minutes depending on your hardware capabilities. Upon successful completion, the compiled kernel image, named bzImage, will be located in the arch/x86/boot/ directory.
Deploying the Kernel to Windows 11
The compiled kernel currently resides within the WSL2 file system. To configure Windows 11 to use it, you must move the kernel image to the Windows host file system.
Create a dedicated directory in your Windows user profile to store custom WSL configurations and copy the kernel image:
mkdir -p /mnt/c/Users/$(cmd.exe /c echo %USERNAME% | tr -d '\r')/wsl_custom
cp arch/x86/boot/bzImage /mnt/c/Users/$(cmd.exe /c echo %USERNAME% | tr -d '\r')/wsl_custom/custom_kernel
Configuring the .wslconfig File
Windows 11 determines global WSL2 settings via a configuration file named .wslconfig, located in the root of your Windows user directory. You must edit this file to instruct the WSL hypervisor to boot using your newly compiled kernel.
Open or create the .wslconfig file using a Windows text editor (or via the WSL terminal):
nano /mnt/c/Users/$(cmd.exe /c echo %USERNAME% | tr -d '\r')/.wslconfig
Add the following configuration block, ensuring you replace `YOUR_USERNAME` with your actual Windows account name. Note the use of double backslashes for the Windows file path:
[wsl2] kernel=C:\\Users\\YOUR_USERNAME\\wsl_custom\\custom_kernel
Save the file and exit the editor.
Applying the Configuration and Verifying the Kernel
For the new kernel configuration to take effect, you must perform a complete shutdown of the WSL2 subsystem. This terminates the hypervisor instance and forces it to reload the configuration upon the next launch.
Open a standard Windows PowerShell or Command Prompt window (not a WSL terminal) and execute the shutdown command:
wsl --shutdown
Relaunch your preferred Linux distribution from the Start menu or Windows Terminal. Once the environment boots, verify that the custom kernel is actively running by checking the kernel release information:
uname -r
The output should reflect the version of the kernel you just compiled, often appended with a -microsoft-standard-custom tag if you did not modify the localversion string during configuration. Your Windows 11 WSL2 environment is now operating on your bespoke Linux kernel, ready for advanced development workloads.