Skip to content

wsl2: cover custom WSL2 kernels #21956

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 4, 2025
Merged

wsl2: cover custom WSL2 kernels #21956

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c0759e6
wsl2: cover custom WSL2 kernels
Feb 3, 2025
8d044da
Apply suggestions from code review
aevesdocker Feb 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions content/manuals/desktop/features/wsl/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
34 changes: 34 additions & 0 deletions content/manuals/desktop/features/wsl/custom-kernels.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
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]
aliases:
- /desktop/wsl/custom-kernels/
---

Docker Desktop depends on several kernel features built into the default
WSL 2 Linux kernel distributed by Microsoft. Because of that, **using a
custom kernel with Docker Desktop on WSL 2 is not officially supported**
and may cause issues with Docker Desktop startup or operation.

At the same time, we understand that in some cases it may be necessary

Check warning on line 15 in content/manuals/desktop/features/wsl/custom-kernels.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.We] Avoid using first-person plural like 'we'.

Raw Output:
{"message": "[Docker.We] Avoid using first-person plural like 'we'.", "location": {"path": "content/manuals/desktop/features/wsl/custom-kernels.md", "range": {"start": {"line": 15, "column": 19}}}, "severity": "WARNING"}
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, we suggest starting

Check warning on line 19 in content/manuals/desktop/features/wsl/custom-kernels.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.We] Avoid using first-person plural like 'we'.

Raw Output:
{"message": "[Docker.We] Avoid using first-person plural like 'we'.", "location": {"path": "content/manuals/desktop/features/wsl/custom-kernels.md", "range": {"start": {"line": 19, "column": 39}}}, "severity": "WARNING"}
from the kernel tree distributed by Microsoft at their [official
repository](https://github.com/microsoft/WSL2-Linux-Kernel) and adding
the features you need on top of that.

We suggest to:

Check warning on line 24 in content/manuals/desktop/features/wsl/custom-kernels.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[Docker.We] Avoid using first-person plural like 'We'.

Raw Output:
{"message": "[Docker.We] Avoid using first-person plural like 'We'.", "location": {"path": "content/manuals/desktop/features/wsl/custom-kernels.md", "range": {"start": {"line": 24, "column": 1}}}, "severity": "WARNING"}
- 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
in 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`).