Build, package, and boot a custom Microsoft WSL2 kernel from Ubuntu on WSL, while keeping the resulting bzImage, kernel config, and modules payload in a GitHub-friendly project layout.
This project captures a real end-to-end run completed on March 13, 2026 on a Windows machine using Ubuntu-24.04 under WSL2.
Reproducible WSL2 custom kernel workflow for Windows using Microsoft's WSL kernel source, with checked-in kernel artifacts, exact config snapshots, PowerShell activation scripts, release notes, and detailed step-by-step documentation.
wslwsl2linux-kernelwindowsubuntukernel-buildcustom-kernelpowershellmicrosoftdeveloper-environment
- checked-in custom WSL kernel image
- checked-in split modules VHDX parts for GitHub compatibility
- source and running kernel config snapshots
- pinned kernel source submodule reference
- build script for Ubuntu on WSL
- activation and rollback scripts for Windows PowerShell
- detailed docs for build, boot, verification, rollback, and publishing
- Host OS: Windows
- WSL distro:
Ubuntu-24.04 - Original kernel before override:
6.6.87.2-microsoft-standard-WSL2 - Active custom kernel after override:
6.6.87.2-microsoft-standard-WSL2+ - Source repo: microsoft/WSL2-Linux-Kernel
- Source branch used:
user/chessturo/6.6.87.2 - Build config entrypoint:
Microsoft/config-wsl
- docs/BUILD.md
- docs/BOOT.md
- docs/GITHUB_METADATA.md
- docs/RELEASE_NOTES.md
- artifacts
- configs
- source
- scripts
Build from Ubuntu on WSL:
cd /mnt/c/Users/ManishKL/Documents/Playground/wsl-custom-kernel
bash scripts/build_wsl_kernel.shActivate from Windows PowerShell:
Set-Location C:\Users\ManishKL\Documents\Playground\wsl-custom-kernel
powershell -ExecutionPolicy Bypass -File .\scripts\assemble_modules_vhdx.ps1
powershell -ExecutionPolicy Bypass -File .\scripts\apply_wsl_custom_kernel.ps1Verify:
wsl -d Ubuntu-24.04 uname -rExpected output:
6.6.87.2-microsoft-standard-WSL2+
This workflow uses Microsoft's WSL kernel tree. A plain upstream Linux defconfig kernel is not the right first target if your goal is to boot WSL successfully.
The exact kernel source is pinned in the repo as a submodule reference at source/WSL2-Linux-Kernel. Because this kernel tree does not check out cleanly onto this Windows NTFS workspace, initialize and use that submodule from WSL when you need the full source tree on disk.
GitHub LFS rejects individual files larger than 2 GiB. The exact modules.vhdx for this build is larger than that limit, so the repository stores it as split LFS chunks:
artifacts/modules-6.6.87.2-microsoft-standard-WSL2+.vhdx.part-00artifacts/modules-6.6.87.2-microsoft-standard-WSL2+.vhdx.part-01
Reassemble them locally before applying the custom kernel:
powershell -ExecutionPolicy Bypass -File .\scripts\assemble_modules_vhdx.ps1