Docker Desktop Fails After a WSL Custom Kernel: Isolate It Safely

Freeze the kernel change before resetting anything

A Docker Desktop startup failure on the WSL backend is not a reason to run factory reset first. That can erase both evidence and data. Docker states that custom kernels on WSL 2 are not officially supported and that Docker Desktop depends on features present in the Microsoft-provided default WSL kernel. If the problem began after adding kernel= to .wslconfig, the least destructive test is an A/B comparison with the default kernel.

Do not declare the custom kernel guilty before the comparison. An outdated WSL installation, disabled virtualization, an unhealthy Docker internal distribution, or a conflicting Docker Engine installation can produce a similar startup symptom. Record the change time and the kernel that actually booted.

Capture a Windows baseline

Item	Value to capture	Decision
WSL installation	WSL and kernel versions	Confirm Docker’s minimum WSL 2.1.5 requirement.
Distribution mode	The VERSION column	Confirm that the integrated distribution uses WSL 2.
System kernel	wsl --system uname -r	Record the kernel that actually booted.
Global settings	%UserProfile%\.wslconfig	Identify kernel and kernelModules overrides.
Docker diagnostics	Diagnostic ID and local bundle path	Preserve the pre-change failure state.

wsl --version
wsl --status
wsl -l -v
wsl --system uname -r
Get-Content "$env:USERPROFILE\.wslconfig" -ErrorAction SilentlyContinue
docker desktop diagnose

If wsl --version does not print a component version table, the machine may still use the older inbox WSL path. Docker documents WSL 2.1.5 as the minimum and recommends current WSL releases. Do not combine a WSL update and a kernel comparison in one unexplained change.

Run a reversible default-kernel comparison

Close Docker Desktop and all WSL distributions. Back up the entire .wslconfig before temporarily renaming it. This removes memory and networking settings as well as the kernel override. Therefore, a changed result narrows the problem to the file but does not yet prove that only the kernel caused it. A follow-up test should remove just kernel= and kernelModules=.

$cfg = "$env:USERPROFILE\.wslconfig"
Copy-Item $cfg "$cfg.before-docker-test" -ErrorAction Stop
Rename-Item $cfg ".wslconfig.disabled"
wsl --shutdown
wsl --system uname -r

After the Microsoft default kernel boots, start Docker Desktop and verify more than the dashboard. Check the Engine and the distribution integration.

docker version
wsl -l -v
wsl -d Ubuntu -- docker version

Replace the final distribution name with the one enabled for integration. If WSL Integration is disabled for that distribution, a missing Docker CLI connection there can be expected even when the Engine is healthy.

Interpret the A/B result

• Only the default kernel starts Docker: the custom kernel or another option removed with the file is in scope. Docker recommends starting from the Microsoft WSL2-Linux-Kernel tree and matching the kernel version distributed with the current WSL release. Compare required Docker features before rebuilding.
• The default kernel also fails: suspend the custom-kernel hypothesis. Verify that WSL commands run, virtualization and Windows features are enabled, and the Docker diagnostic identifies the failing component.
• Docker starts but one distribution cannot use the CLI: inspect Docker Desktop WSL Integration and the distribution mode. This is separate from failure of the internal Engine to start.
• wsl --system uname -r does not change: a WSL VM may still be running or a different settings file may be in use. Recheck active distributions and the file path before rebooting.

When the custom kernel must remain

Docker recommends using the same kernel version as the latest WSL 2 release, starting from Microsoft’s official kernel tree, and matching pahole with CONFIG_PAHOLE_VERSION. Meeting those recommendations does not turn a custom kernel into an officially supported Docker Desktop configuration.

Do not change Docker data, unregister a distribution, and replace the kernel in one experiment. When both the kernel file and modules VHD change, record the pair, run wsl --shutdown, and capture the active kernel string again.

Rollback

To restore the original settings after the default-kernel test, close Docker Desktop and WSL, then restore the saved filename. Ensure that the disabled and active files do not coexist.

wsl --shutdown
Rename-Item "$env:USERPROFILE\.wslconfig.disabled" ".wslconfig"
Get-Content "$env:USERPROFILE\.wslconfig"
wsl --system uname -r

If Docker fails again after the custom kernel returns, that result is useful reproduction evidence. Preserve WSL, kernel, and Docker Desktop versions with the diagnostic ID. Treat any data reset as a separate, explicitly approved operation.

Related guides

• Server and operating-system troubleshooting
• Docker and container troubleshooting
• All troubleshooting topics

Official references

• Docker custom kernels on WSL – support boundary and kernel-build recommendations
• Docker Desktop WSL 2 backend – WSL requirements and integration scope
• Microsoft .wslconfig reference – kernel, kernelModules, and configuration scope
• Microsoft WSL basic commands – version, status, update, and shutdown behavior
• Docker Desktop troubleshooting – diagnostics and the distinction from destructive reset options

Earlier verification notes preserved from this article

Verification level: official documentation checked

The WSL kernel boundary documented by Docker and Microsoft was reviewed directly. No specific custom kernel config was reproduced, so the guide avoids guessing a missing kernel option and limits itself to reversible isolation.

Writing and correction policy · Report an error