Skip to content

Commit 8b264bd

Browse files
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 <[email protected]>
1 parent 272478e commit 8b264bd

File tree

2 files changed

+33
-0
lines changed

2 files changed

+33
-0
lines changed

content/manuals/desktop/features/wsl/_index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,3 +109,4 @@ Docker Desktop does not require any particular Linux distributions to be install
109109
- [Explore best practices](best-practices.md)
110110
- [Understand how to develop with Docker and WSL 2](use-wsl.md)
111111
- [Learn about GPU support with WSL 2](/manuals/desktop/features/gpu.md)
112+
- [Custom kernels on WSL](custom-kernels.md)
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: Custom kernels on WSL
3+
description: Using custom kernels with Docker Desktop on WSL 2
4+
keywords: wsl, docker desktop, custom kernel
5+
tags: [Best practices, troubleshooting]
6+
---
7+
8+
Docker Desktop depends on several kernel features built into the default
9+
WSL 2 Linux kernel distributed by Microsoft. Consequently, using a
10+
custom kernel with Docker Desktop on WSL 2 is not officially supported
11+
and may cause issues with Docker Desktop startup or operation.
12+
13+
However, in some cases it may be necessary
14+
to run custom kernels; Docker Desktop does not block their use, and
15+
some users have reported success using them.
16+
17+
If you choose to use a custom kernel, it is recommended you start
18+
from the kernel tree distributed by Microsoft from their [official
19+
repository](https://github.com/microsoft/WSL2-Linux-Kernel) and then add
20+
the features you need on top of that.
21+
22+
It's also recommended that you:
23+
- Use the same kernel version as the one distributed by the latest WSL2
24+
release. You can find the version by running `wsl.exe --system uname -r`
25+
in a terminal.
26+
- Start from the default kernel configuration as provided by Microsoft
27+
from their [repository](https://github.com/microsoft/WSL2-Linux-Kernel)
28+
and add the features you need on top of that.
29+
- Make sure that your kernel build environment includes `pahole` and
30+
its version is properly reflected in the corresponding kernel config
31+
(`CONFIG_PAHOLE_VERSION`).
32+

0 commit comments

Comments
 (0)