-
Notifications
You must be signed in to change notification settings - Fork 808
Ship WSL 2 Linux Kernel
WSL 2 distributions use a full Linux kernel. This Linux kernel is open source, with its source code available at the WSL2-Linux-Kernel repository. At the beginning, Linux kernel is shipped as a Windows component and delivered as part of Windows. To improve the serviceability, The Linux kernel is lifted and removed from Windows, then is going to deliver to your machine via Microsoft Update automatically, and follows a separate release schedule to the Windows Subsystem for Linux which is delivered as part of the Windows image.
The whole serving story is divided into three steps:
- Create MSI installer to install Linux kernel.
- Remove Linux kernel from Windows. When you see
WSL 2 requires an update to its kernel component. For information please visit https://aka.ms/wsl2kernel
, that means you are in this step. - Linux kernel update is delivered to your machine automatically by Microsoft Update.
To use WSL 2, kernel
is expected in %SystemRoot%\system32\lxss\tools\
. In the earlier version of OS, kernel is shipped with OS. Then kernel is lifted and removed from OS image and is packaged into a MSI installer which named Windows Subsystem for Linux Update
.
To install MSI kernel, WSL is required and should be enabled first. If it fails, it pops up the message:
This update only applies to machines with the Windows Subsytem for Linux
.
There are three possible reason you see this message:
-
You are still in old version of Windows which doesn't support WSL 2. Please check the WSL 2 requirement
-
Windows Subsystem for Linux
is not enabled. Please follow Windows Subsystem for Linux Installation Guide -
After you enabled
Windows Subsystem for Linux
, reboot is required to take into effect.
If Pre-Check step passed, the installer continues:
- Copy kernel to kernel.rollback
- Install and replace kernel file
If Linux kernel is removed from Windows image, you will see this error message:
WSL 2 requires an update to its kernel component. For information please visit https://aka.ms/wsl2kernel
. Follow above link, and most of the user should be able resolved the problem after install the kernel manually.
Note: this is not public API and implementation is subject to change
Kernel is delivered by Microsoft Update, and two version of kernels are kept in tools: kernel
and kernel.rollback
. You are able to rollback to previous version by wsl --update --rollback
, but
wsl.exe doesn't provide public interface to revert the rollback. It's by design.
When rollback happens, it's assumed that this version is bad and user should not pickup this version again. Assume Microsoft shipped three versions of version:
A(.104) -> B(.121) -> C(.1xy)
User hits problem on version B(.121), then user rolled back to A(.104). So no public interface is provided for you to revert the rollback. Here is the status of kernel:
kernel | kernel.rollback |
---|---|
B(.121) | A(.104) |
When bug fix for B is ready and C is shipped, user picks up C automatically by Windows Update. Since B is assumed bad and A is good, user is not allowed to rollback to B too but A. Here is the actual mapping after user updates to C:
kernel | kernel.rollback |
---|---|
C(.1xy) | A(.104) |
version B(.121) is dropped because it's assumed bad and it's only allowed to rollback from C to A(.104)
see Pre-Check Step
WSL 2 requires an update to its kernel component. For information please visit https://aka.ms/wsl2kernel
Each time kernel is missing in %SystemRoot%\system32\lxss\tools, you may run into above error. There are many reasons:
- User just start to setup WSL 2
- WSL 2 is enabled before, and Windows is updated to latest version
- MSI is installed, but kernel file is missing.
Not matter what reason, there is no %SystemRoot%\system32\lxss\tools\kernel
exists. Here are some possible ways to resolve it:
- If you didn't install MSI manually before, download and install it from https://aka.ms/wsl2kernel
- If there is
%SystemRoot%\system32\lxss\tools\kernel.rollback
, copy it to%SystemRoot%\system32\lxss\tools\kernel
- Uninstall the MSI from 'Add or Remove Programs', and install it again
- Extract kernel from .msi and copy kernel to tools directory
msiexec /a "wsl_update_x64.msi" /qb TARGETDIR="C:\temp"
- copy the kernel file from C:\temp to
%SystemRoot%\System32\lxss\tools
MSI installer keeps two version of kernel, if you find kernel.rollback
in tools, then you are able to rollback to an old version of kernel.
dir %SystemRoot%\system32\lxss\tools\kernel*
You can rollback the kernel with below command which requires admin permission.
wsl.exe --update --rollback
wsl --shutdown
Please note that --shutdown
stops both WSL 1 and WSL 2 instances.
After wsl --update --rollback
, the running instance doesn't pick up the kernel immediately, you have to save your work, then shutdown and restart the Linux.
Note: this is not public API and implementation is subject to change
wsl doesn't provides public interface for you to revert the rollback, but you still be able to do it manually:
deleting RollbackKernel in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss
wsl --shutdown