https://github.com/locietta/xanmod-kernel-wsl2
Xanmod kernel for WSL2, built by clang with ThinLTO enabled. Build & Release are automated by Github Action.
https://github.com/locietta/xanmod-kernel-wsl2
automated kernel linux wsl2 wsl2-kernel
Last synced: 1 day ago
JSON representation
Xanmod kernel for WSL2, built by clang with ThinLTO enabled. Build & Release are automated by Github Action.
- Host: GitHub
- URL: https://github.com/locietta/xanmod-kernel-wsl2
- Owner: Locietta
- License: gpl-2.0
- Created: 2022-03-13T09:13:34.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2026-05-26T03:00:34.000Z (20 days ago)
- Last Synced: 2026-05-26T04:09:00.389Z (20 days ago)
- Topics: automated, kernel, linux, wsl2, wsl2-kernel
- Language: Shell
- Homepage:
- Size: 1.15 MB
- Stars: 236
- Watchers: 11
- Forks: 39
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# xanmod-kernel-WSL2
An **unofficial** [XanMod](https://gitlab.com/xanmod/linux) kernel port for **Windows Subsystem for Linux 2 (WSL2)**, featuring:
- **Microsoft's dxgkrnl** patches for GPU support
- **Compiled with Clang + ThinLTO** for additional optimizations
- **Automated builds** via GitHub Actions (always up-to-date)
- **Multiple CPU-optimized variants** (x64v2, x64v3, Skylake, Zen3)
## Usage
### Install via Scoop (Recommended)
[scoop](https://scoop.sh/) is a command-line installer on windows that makes installation and update easy. We provide scoop manifests for this kernel in the [Locietta/sniffer](https://github.com/Locietta/sniffer) repository.
#### Installation
```bash
# Add the repository
scoop bucket add sniffer https://github.com/Locietta/sniffer
# Install kernel (alias to x64v3 variant, works for most modern CPUs)
scoop install xanmod-WSL2
# Optional: Install addons (extra modules, headers, documentation)
scoop install xanmod-WSL2-addons
# Restart WSL2 to apply
wsl --shutdown
```
Expand all other builds
```bash
# other MAIN builds
# scoop install xanmod-WSL2-{x64v2, x64v3, skylake, zen3}
# scoop install xanmod-WSL2-addons-{x64v2, x64v3, skylake, zen3}
# LTS builds
# scoop install xanmod-WSL2-lts # alias to xanmod-WSL2-lts-x64v3
# scoop install xanmod-WSL2-lts-addons
# scoop install xanmod-WSL2-lts-{x64v2, x64v3, skylake, zen3}
# scoop install xanmod-WSL2-addons-lts-{x64v2, x64v3, skylake, zen3}
```
**That's it!** Scoop automatically configures everything for you.
#### Update kernel
Run `scoop update *` to update all scoop installed apps including this kernel.
We recommend to run `scoop update *` instead of `scoop update xanmod-WSL2` alone to make sure the addons package is also updated and in sync with the kernel.
> **NOTE:** To make the kernel update applied, you have to reboot WSL2 after running scoop update!
### Manual Installation
It's also straightforward to manually install this kernel. For each arch, we release two files: the kernel image `bzImage` and an optional addon archive `bzImage-addons.vhdx.7z` that contains the VHDX with extra modules, headers and documentation.
The manual installation steps are as follows:
- Download kernel image from [releases](https://github.com/Locietta/xanmod-kernel-WSL2/releases)
- optionally, download the addon archive if you need extra modules/headers/docs, then extract the `.vhdx` file from it
- Place it to somewhere appropriate. (e.g. `D:\.WSL\bzImage`)
- Edit and save the `%UserProfile%\.wslconfig` with following content:
```ini
[wsl2]
kernel = the\\path\\to\\bzImage
kernelModules = the\\path\\to\\bzImage-addons.vhdx ; optional
; e.g.
; kernel = D:\\.WSL\\bzImage
; kernelModules = D:\\.WSL\\bzImage-addons.vhdx
;
; Note that all `\` should be escaped with `\\`.
```
- Reboot your WSL2 to check your new kernel and enjoy!
## Troubleshooting
### Changes not applied after installation or update?
You must fully shut down WSL2 utill no WSL2 instances are running, then start it again to apply the new kernel.
```powershell
wsl --shutdown
wsl --list --running # Should show "no running distributions"
```
### Modules are not loaded to `/lib/modules`?
Modules VHDX support is only available with WSL version **2.5.1** or later. Try running `wsl --version` to check your WSL version and use `wsl --update` to update WSL if needed.
### WSL fails to boot with `E_ACCESSDENIED` after configuring `kernelModules`?
If WSL fails to start with `Wsl/Service/CreateInstance/CreateVm/HCS/E_ACCESSDENIED`, your `kernelModules` vhdx is missing NTFS ACL entries that WSL **2.7.1+** requires (see [#153](https://github.com/Locietta/xanmod-kernel-WSL2/issues/153)). This commonly happens when the vhdx lives under your user profile (e.g. `C:\Users\\...`), where the default DACL doesn't grant access to the AppContainer principals WSL uses.
Scoop handles this automatically. For **manual installation**, after extracting the vhdx run the following PowerShell command to grant the necessary permissions:
```powershell
icacls "path\to\bzImage-addons.vhdx" /grant `
"*S-1-5-32-545:(RX)" `
"*S-1-15-2-1:(RX)" `
"*S-1-15-2-2:(RX)"
```
This grants `BUILTIN\Users`, `ALL APPLICATION PACKAGES`, and `ALL RESTRICTED APPLICATION PACKAGES` read-and-execute on the vhdx.
### Can't find `.wslconfig` file?
It doesn't exist by default. Just create it manually in your user profile folder (e.g. `C:\Users\YourName\.wslconfig`).
> For more information about `.wslconfig`, see microsoft's official [documentation](https://docs.microsoft.com/en-us/windows/wsl/wsl-config#configure-global-options-with-wslconfig).
### Which architecture should I choose?
If you are unsure whether to use x64v2 or x64v3, you can visit [xanmod.org](https://xanmod.org/). There's literally a table showing all the CPU models and their corresponding x86_64 psABI levels.
You can also get a [checking script](https://dl.xanmod.org/check_x86-64_psabi.sh) from there.
## Development
🚧WIP
## Credits
- Linux community for the awesome OS kernel.
- Microsoft for WSL2 and dxgkrnl patches.
- XanMod project for various optimizations.
- LLVM/Clang for the compiler infrastructure.
## Contributing
We welcome contributions! You can:
* 🐛 Report bugs by opening an [issue](https://github.com/Locietta/xanmod-kernel-WSL2/issues/new?template=bug_report.yml)
* 💡 Suggest features via [issues](https://github.com/Locietta/xanmod-kernel-WSL2/issues/new?template=feature-request.yml)
* 🔧 Submit improvements through [pull requests](https://github.com/Locietta/xanmod-kernel-WSL2/pulls)