wsl2: cover custom WSL2 kernels (#21956)

## Description

Many customers wonder whether they can use custom kernels on WSL2 and
whether that's officially supported. Explain it is not, but also clarify
that they can do that at their own risk.

Also provide some helpful suggestins.

## Related issues or tickets

<!-- List applicable reviews (optionally @tag reviewers) -->

- [X] Technical review
- [X] Editorial review
- [X] Product review

---------

Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com>
This commit is contained in:
Andrea Reale 2025-02-04 10:50:24 +01:00 committed by GitHub
parent 272478ea34
commit 8b264bd54f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 33 additions and 0 deletions

View File

@ -109,3 +109,4 @@ Docker Desktop does not require any particular Linux distributions to be install
- [Explore best practices](best-practices.md)
- [Understand how to develop with Docker and WSL 2](use-wsl.md)
- [Learn about GPU support with WSL 2](/manuals/desktop/features/gpu.md)
- [Custom kernels on WSL](custom-kernels.md)

View File

@ -0,0 +1,32 @@
---
title: Custom kernels on WSL
description: Using custom kernels with Docker Desktop on WSL 2
keywords: wsl, docker desktop, custom kernel
tags: [Best practices, troubleshooting]
---
Docker Desktop depends on several kernel features built into the default
WSL 2 Linux kernel distributed by Microsoft. Consequently, using a
custom kernel with Docker Desktop on WSL 2 is not officially supported
and may cause issues with Docker Desktop startup or operation.
However, in some cases it may be necessary
to run custom kernels; Docker Desktop does not block their use, and
some users have reported success using them.
If you choose to use a custom kernel, it is recommended you start
from the kernel tree distributed by Microsoft from their [official
repository](https://github.com/microsoft/WSL2-Linux-Kernel) and then add
the features you need on top of that.
It's also recommended that you:
- Use the same kernel version as the one distributed by the latest WSL2
release. You can find the version by running `wsl.exe --system uname -r`
in a terminal.
- Start from the default kernel configuration as provided by Microsoft
from their [repository](https://github.com/microsoft/WSL2-Linux-Kernel)
and add the features you need on top of that.
- Make sure that your kernel build environment includes `pahole` and
its version is properly reflected in the corresponding kernel config
(`CONFIG_PAHOLE_VERSION`).