xanmod-kernel-WSL2

An unofficial XanMod 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 is a command-line installer on windows that makes installation and update easy. We provide scoop manifests for this kernel in the Locietta/sniffer repository.

Installation

# 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

That's it! Scoop automatically configures everything for you.

Expand all other builds

# 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}

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
  • 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:

[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!

When the addon VHDX is configured, WSL exposes the packaged artifacts below /lib/modules/$(uname -r):

• build/ is the prepared kbuild tree for compiling external kernel modules.
• build/usr/include/ contains the sanitized userspace API headers exported by make headers_install.
• build/Documentation/ contains the documentation from the matching kernel sources.

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.

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.

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.

Which architecture should I choose?

If you are unsure whether to use x64v2 or x64v3, you can visit 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 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
• 💡 Suggest features via issues
• 🔧 Submit improvements through pull requests