Fix “WSL kernel update required” the Clean Way

What the error really means (and what it doesn’t)

“WSL kernel update required” is Windows telling you that the Linux kernel used by WSL2 is missing, too old, or incompatible with the WSL components currently installed. It’s not complaining about your Ubuntu packages. It’s not asking you to apt upgrade. It’s the WSL platform saying: “I can’t boot the VM-like environment because the kernel piece isn’t in the state I expect.”

In practice, it’s usually one of these:

• WSL app (Store version) updated but the kernel package didn’t, so the app expects a newer kernel interface.
• Windows updated and WSL is now stricter about kernel version or location.
• WSL2 kernel not installed (common on older images, offline builds, or machines that skipped the kernel MSI).
• Virtualization not available (Hyper-V stack isn’t active, VBS policies changed, BIOS toggled, or the VM platform feature is off), and the error message is merely the first one you see.
• Corporate hardening blocked the Store, blocked downloads, or pinned components into an awkward mismatch.

If you treat this as a “Linux problem,” you’ll waste time. This is a Windows component alignment problem. The fix is to align: Windows features, WSL app, kernel, and virtualization.

One paraphrased idea from the reliability world: paraphrased idea — John Allspaw often emphasizes that incidents are about systems, not individual mistakes. This error is a system mismatch dressed up as a single message.

Joke #1: WSL errors are like office printers: they don’t fail when you’re bored, they fail when you’re five minutes from a deadline.

Interesting facts & short history you can weaponize

Knowing how WSL got here helps you debug it faster. A few concrete facts that matter in real-world operations:

1. WSL1 vs WSL2 are fundamentally different: WSL1 translates Linux syscalls; WSL2 runs a real Linux kernel in a lightweight VM. “Kernel update required” is a WSL2-class problem.
2. WSL2’s kernel is maintained and delivered by Microsoft (it’s a Linux kernel build with WSL-specific integration). You’re not compiling your own unless you choose to.
3. The WSL kernel used to be installed via an MSI package separate from Windows Updates. That legacy still shows up in enterprise environments and offline images.
4. WSL moved into the Microsoft Store for faster updates independent of full OS releases. That’s great for velocity and terrible for locked-down fleets unless you plan for it.
5. “wsl.exe” is the control plane: it can report versions, manage distros, set defaults, and update WSL. Most “fixes” should start with it, not random reinstalls.
6. Docker Desktop pushed many orgs onto WSL2 because it’s the practical default for local containers on Windows. So WSL kernel issues often show up as “Docker is broken.”
7. Virtualization-based security (VBS) and hypervisor settings can affect whether WSL2 can even start. Your kernel can be perfect and still not boot.
8. The WSL kernel lives outside your distro filesystem. Resetting Ubuntu won’t fix a missing kernel. It may just delete your data while the real problem remains.
9. WSLg (GUI apps) rides on the same infrastructure. A kernel mismatch can break not only shells and containers but also Linux GUI apps on Windows.

That’s the framing. Now let’s go fix it like adults.

Fast diagnosis playbook

When you’re on call for developer productivity (yes, that’s a thing), you don’t start with reinstalling. You start with a three-question funnel:

1) Is this WSL2 kernel/version mismatch or virtualization failure?

• If wsl --status shows a kernel version and wsl -d still fails, it’s often an app/kernel mismatch or broken distro config.
• If you get errors mentioning virtualization, Hyper-V, or codes like 0x80370102, you’re in “platform features/BIOS” territory.

2) Is your WSL delivered via Store or inbox Windows component?

• Store-managed WSL typically updates via wsl --update (and sometimes via Store mechanisms you can’t see).
• In locked-down environments, Store is blocked, so you need an approved offline/update channel.

3) What changed last?

• Windows cumulative update?
• Security baseline / group policy rollout?
• Docker Desktop update?
• A BIOS/firmware update that toggled virtualization settings?

Don’t overthink it. The fastest path is to gather the minimum facts and then choose a fix lane: update WSL, repair features, or fix virtualization.

Practical tasks: commands, outputs, and decisions

These are real tasks I’d run on a Windows box (PowerShell) and inside a WSL distro (bash). Each task includes: a command, what the output means, and the decision you make from it.

Task 1: Confirm WSL is installed and see basic status

cr0x@server:~$ wsl --status
Default Distribution: Ubuntu
Default Version: 2
WSL version: 2.1.5.0
Kernel version: 5.15.153.1-2
WSLg version: 1.0.61
MSRDC version: 1.2.5105
Direct3D version: 1.611.1-81528511
DXCore version: 10.0.26100.1-240331-1435.ge-release
Windows version: 10.0.22631.3007

Meaning: WSL is present, and the kernel version is visible. If the kernel line is missing or blank, your kernel install/update is suspect.

Decision: If you see a kernel version but still get “kernel update required,” you likely need wsl --update or a repair. If you don’t see a kernel version, prioritize kernel installation/update.

Task 2: List distros and identify which ones are WSL1 vs WSL2

cr0x@server:~$ wsl -l -v
  NAME            STATE           VERSION
* Ubuntu          Stopped         2
  Debian          Running         2
  Alpine          Stopped         1

Meaning: You have multiple distros; one is WSL1. Only WSL2 needs the kernel.

Decision: If the failing distro is WSL2, continue. If it’s WSL1, this error message is a clue you’re actually launching WSL2 tooling or Docker, not that distro.

Task 3: Check the WSL version and whether you’re on Store WSL

cr0x@server:~$ wsl --version
WSL version: 2.1.5.0
Kernel version: 5.15.153.1-2
WSLg version: 1.0.61
MSRDC version: 1.2.5105
Direct3D version: 1.611.1-81528511
DXCore version: 10.0.26100.1-240331-1435.ge-release
Windows version: 10.0.22631.3007

Meaning: On modern systems, wsl --version exists and prints component versions. On older inbox WSL, this command may error or print less.

Decision: If wsl --version doesn’t work, you may be on older/inbox WSL; updating via Store may be required (or blocked), so plan accordingly.

Task 4: Attempt a clean update of WSL components

cr0x@server:~$ wsl --update
Checking for updates...
Installing: Windows Subsystem for Linux
Update successful.

Meaning: WSL updated successfully (this can include the kernel package depending on your channel).

Decision: Retry launching the failing distro. If it still fails, move on to kernel location/config checks and feature verification.

Task 5: Shut down WSL cleanly (don’t fight zombie VMs)

cr0x@server:~$ wsl --shutdown

Meaning: Terminates all running WSL instances and the lightweight VM backend.

Decision: Always do this after updates or feature toggles. If restarting fixes it, you had a stale runtime state.

Task 6: Confirm virtualization is available (fast sanity check)

cr0x@server:~$ systeminfo.exe
...
Hyper-V Requirements:      VM Monitor Mode Extensions: Yes
                           Virtualization Enabled In Firmware: Yes
                           Second Level Address Translation: Yes
                           Data Execution Prevention Available: Yes

Meaning: If “Virtualization Enabled In Firmware: No” shows up, WSL2 won’t boot regardless of kernel version.

Decision: If firmware virtualization is off, fix BIOS/UEFI settings first. If it’s on, continue with Windows feature checks.

Task 7: Verify Windows features required for WSL2

cr0x@server:~$ dism.exe /online /get-features /format:table | findstr /i /c:"VirtualMachinePlatform" /c:"Microsoft-Windows-Subsystem-Linux"
Microsoft-Windows-Subsystem-Linux   Enabled
VirtualMachinePlatform              Enabled

Meaning: Both features must be enabled for WSL2. If either is disabled, WSL2 kernel boot can fail or behave oddly.

Decision: If disabled, enable them and reboot. Don’t skip the reboot because you “feel lucky.”

Task 8: Enable missing features (and accept the reboot)

cr0x@server:~$ dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
...
The operation completed successfully.

cr0x@server:~$ dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
...
The operation completed successfully.

Meaning: Features are enabled, but the system state may still require a reboot to load hypervisor components.

Decision: Reboot. Then run wsl --status again.

Task 9: Validate the default WSL version (don’t assume)

cr0x@server:~$ wsl --set-default-version 2
For information on key differences with WSL 2 please visit https://aka.ms/wsl2
The operation completed successfully.

Meaning: New distros will default to WSL2. Existing ones keep their version until converted.

Decision: If your target distro is WSL1 and you need WSL2 features (Docker integration, better syscall compatibility), convert it. If you just need a working shell quickly, WSL1 can be a temporary escape hatch.

Task 10: Convert a distro to WSL2 (or back to WSL1 for containment)

cr0x@server:~$ wsl --set-version Ubuntu 2
Conversion in progress, this may take a few minutes...
For information on key differences with WSL 2 please visit https://aka.ms/wsl2
Conversion complete.

Meaning: This uses a virtual disk; conversion time depends on size and I/O.

Decision: If conversion fails with kernel-related errors, your platform/kernel problem is real; don’t keep poking the distro.

Task 11: Force a specific kernel (only if you know why)

cr0x@server:~$ notepad.exe %UserProfile%\.wslconfig

Example config you might find or add:

cr0x@server:~$ type %UserProfile%\.wslconfig
[wsl2]
kernel=C:\\WSL\\kernel
memory=8GB
processors=4

Meaning: A custom kernel path overrides the default. If that file points to a missing or old kernel, you’ll get “kernel update required” or boot failures.

Decision: If you didn’t intend to run a custom kernel, remove the kernel= line or fix the path. Custom kernels are a maintenance commitment, not a vibe.

Task 12: Check if a proxy or SSL inspection is breaking updates

cr0x@server:~$ netsh winhttp show proxy
Current WinHTTP proxy settings:

    Proxy Server(s) :  http=proxy.corp.local:8080;https=proxy.corp.local:8080
    Bypass List     :  (none)

Meaning: WSL update mechanisms (and Store delivery) can be sensitive to proxy/inspection setups depending on policy.

Decision: If updates fail with network/SSL errors, coordinate with IT to allow the update channel. Don’t “just disable the proxy” on a managed device unless you like compliance meetings.

Task 13: Look at WSL-related event logs (when the UI lies)

cr0x@server:~$ wevtutil qe Microsoft-Windows-LxssManager/Operational /c:20 /rd:true /f:text
Event[0]:
  Log Name: Microsoft-Windows-LxssManager/Operational
  Source: Microsoft-Windows-LxssManager
  Event ID: 1000
  Level: Error
  Description:
  Failed to start the Linux distribution. Error: 0x800701bc

Meaning: 0x800701bc is commonly associated with needing a kernel update (or kernel package missing).

Decision: Use the code to choose a lane: kernel update vs virtualization. If you see hypervisor-related codes, stop chasing kernel installers.

Task 14: Inside WSL, confirm kernel version (if you can start anything)

cr0x@server:~$ uname -r
5.15.153.1-microsoft-standard-WSL2

Meaning: Confirms what kernel is actually running. If you’re running, the kernel is at least present.

Decision: If Windows claims kernel update required but you can run uname -r, you may have multiple contexts (different user, different WSL installation, or a custom kernel for one account).

Task 15: Check disk space on the Windows system drive (kernel updates need room too)

cr0x@server:~$ dir C:\
 Volume in drive C is Windows
 Volume Serial Number is 1234-ABCD

 Directory of C:\

...
               3 File(s)      1,234,567 bytes
               0 Dir(s)  1,024,000,000 bytes free

Meaning: If free space is tiny, updates can fail in unhelpful ways.

Decision: If you’re scraping the bottom, free space first. WSL isn’t special; it’s just another consumer of a cramped C: drive.

Clean fix paths (pick the right lane)

There are three clean lanes. Choose based on what your diagnostics told you. The worst option is mixing them randomly until something changes. That’s not troubleshooting; that’s gambling with your developer environment.

Lane A: Update WSL properly (preferred when Store is available)

If your environment allows it, wsl --update is the least dramatic solution. Follow it with wsl --shutdown and a relaunch. If you use Docker Desktop, restart it too—Docker caches assumptions about WSL availability.

When this lane works, it’s boring. Boring is good.

Lane B: Repair Windows features and virtualization (preferred when errors smell like hypervisor)

If systeminfo.exe says virtualization is disabled in firmware, stop. Go to BIOS/UEFI and enable Intel VT-x/AMD-V (names vary). If firmware virtualization is enabled but WSL2 still fails, confirm the Windows features are enabled:

• Microsoft-Windows-Subsystem-Linux
• VirtualMachinePlatform

Also be aware of corporate security controls. VBS, Credential Guard, and hypervisor policies can be configured in ways that still allow Hyper-V but break nested or constrained virtualization behavior. Your job here is to find the policy delta, not to “fight Windows.”

Lane C: Offline/managed update channel (preferred in enterprises)

This is where the clean fix becomes political. If the Microsoft Store is blocked, and outbound downloads are restricted, you need an approved mechanism to update WSL and its kernel. The technical part is easy. The process part is why fleets stay on mismatched versions.

If you’re an SRE or platform engineer supporting developer workstations, treat WSL like any other runtime dependency: version it, test it, and roll it out through the same patch pipeline you use for other tooling. WSL is not a personal hobby once it’s the container backend for half your engineering org.

Joke #2: “Just reinstall Windows” is not a fix; it’s a career pivot into interpretive dance.

Three corporate mini-stories from the trenches

Incident: the wrong assumption that lit up the helpdesk

A mid-size company rolled out a Windows update ring that moved a chunk of engineers to a newer build. The WSL app had been installed via the Store for some users, while others had the older inbox WSL. The support team assumed WSL behaved like a Linux package: if it breaks, update the distro.

So the first wave of tickets got the same advice: “Run apt update && apt upgrade in Ubuntu.” It made people feel busy. It did nothing to fix the kernel mismatch. A few users tried reinstalling Ubuntu, which deleted local tooling and SSH keys stored inside the distro. Still broken.

The second wave of tickets got escalated. Someone finally ran wsl --status and saw the kernel version was missing on affected machines. On others, the kernel version existed but was behind what the app expected. The error message was the same; the underlying state was not.

The actual fix was a controlled wsl --update rollout where allowed, and a separate offline kernel update package via the company’s software distribution system where Store access was blocked. Once the team stopped treating WSL as “Ubuntu on Windows” and started treating it as “a Windows-managed virtualization stack,” the incident ended quickly.

Optimization that backfired: “Let’s speed up updates by pinning versions”

Another org tried to be clever. They pinned Windows feature updates to reduce churn, while letting the Store update apps freely because “apps are safe.” WSL was in that “apps” bucket. It updated faster than the OS.

For a while, it was fine. Then the WSL app picked up a change that expected a newer kernel behavior, while the pinned OS build and kernel delivery mechanism lagged. Engineers started seeing “WSL kernel update required,” especially after reboot or after Docker Desktop updated.

The platform team responded by pinning the WSL app too. That reduced incidents but introduced a different failure mode: Docker Desktop began requiring a newer WSL version to enable certain integrations. Now the problem wasn’t a broken shell; it was local container builds failing in confusing ways.

The eventual fix was adult governance: maintain a tested compatibility matrix (Windows build ↔ WSL version ↔ Docker Desktop version), and roll them forward together in a controlled ring. The “optimization” wasn’t pinning. The optimization was coordinating change.

Boring but correct practice that saved the day: a simple preflight check

A finance company had strict endpoint controls and a predictable change window. Their workstation engineering team wrote a preflight script that ran at logon for developers and at imaging time for new machines.

It did three things: checked that virtualization was enabled in firmware (where detectable), verified Windows features for WSL2 were enabled, and checked WSL component versions via wsl --status. If anything looked wrong, it provided a targeted remediation: enable features + reboot, or trigger the approved update workflow.

This script was not fancy. It didn’t auto-fix everything. It didn’t try to outsmart policy. It just prevented the common drift conditions from making it to the user’s Monday morning.

When a kernel mismatch wave hit after a broader OS patch cycle, their ticket volume barely moved. The script caught it. The update ring handled it. Nobody had to learn the hard way that reinstalling Ubuntu doesn’t install the WSL kernel.

Common mistakes: symptoms → root cause → fix

This section exists because people keep doing the same things, confidently, while the system continues to be broken. Let’s put those patterns out of their misery.

1) Symptom: “WSL kernel update required” right after a Windows Update

Root cause: WSL app or OS components updated; kernel package didn’t update or is missing.

Fix: Run wsl --update, then wsl --shutdown, then retry. If Store is blocked, use your enterprise update channel to install the approved WSL/kernel package.

2) Symptom: wsl --update fails with network/proxy errors

Root cause: Corporate proxy/SSL inspection or Store restrictions block WSL’s update channel.

Fix: Verify proxy via netsh winhttp show proxy. Coordinate an allowlist for the update mechanism. Don’t brute-force by disabling security controls on managed devices.

3) Symptom: Error code 0x80370102 or messages about Hyper-V/virtualization

Root cause: Virtualization disabled in BIOS/UEFI, or required Windows features not enabled.

Fix: Confirm with systeminfo.exe. Enable virtualization in firmware. Enable VirtualMachinePlatform and Microsoft-Windows-Subsystem-Linux with DISM, then reboot.

4) Symptom: Only one user account sees the problem

Root cause: Per-user config like %UserProfile%\.wslconfig points at a missing custom kernel, or different WSL installation context.

Fix: Inspect .wslconfig and remove/repair custom kernel overrides unless intentionally managed.

5) Symptom: You can start WSL1 distros but WSL2 fails

Root cause: Kernel/virtualization stack problem. WSL1 doesn’t need the kernel VM.

Fix: Treat as WSL2 platform issue: update WSL, enable features, verify virtualization.

6) Symptom: Reinstalling Ubuntu didn’t help (and now your tools are gone)

Root cause: The kernel is not inside Ubuntu. You deleted a distro to fix a host component.

Fix: Stop reinstalling distros. Fix WSL components. Restore from backups if you had anything important inside the distro filesystem.

7) Symptom: Docker Desktop says WSL2 is required, or containers won’t start

Root cause: Docker is riding WSL2; kernel mismatch prevents the backend from booting.

Fix: Fix WSL first. Then restart Docker Desktop. If Docker updated recently, ensure WSL is updated to a compatible version in your fleet policy.

8) Symptom: Everything worked yesterday, and today it fails only after reboot

Root cause: Pending feature changes or updates didn’t fully apply until reboot; now the mismatch is visible.

Fix: Run wsl --status, wsl --update, and validate features. If you toggled Windows features, reboot again after enabling them properly.

Checklists / step-by-step plan

Checklist A: The clean 10-minute fix (most machines)

1. Run wsl --status. Confirm whether a kernel version is shown.
2. Run wsl --update.
3. Run wsl --shutdown.
4. Launch the failing distro: wsl -d Ubuntu (or your distro name).
5. If it works, stop. Don’t “keep tuning.”

Checklist B: Platform repair when virtualization is the real problem

1. Run systeminfo.exe and read the Hyper-V Requirements section.
2. If virtualization in firmware is “No”: reboot into BIOS/UEFI and enable Intel VT-x/AMD-V.
3. Back in Windows: verify features via DISM (Subsystem-Linux + VirtualMachinePlatform).
4. Enable missing features with DISM.
5. Reboot.
6. Run wsl --status again, then try starting a distro.

Checklist C: Enterprise-safe remediation (Store blocked)

1. Gather facts: wsl --status, wsl --version (if available), wevtutil last 20 WSL events.
2. Confirm your approved update mechanism for WSL (software center, endpoint management tool, offline packages).
3. Apply the approved WSL/kernel update package.
4. wsl --shutdown and reboot if required by your tooling.
5. Validate with wsl --status. Ensure the kernel version is present and current.
6. Document the compatibility set (Windows build + WSL version + Docker Desktop version) for the next rollout.

Checklist D: “It still fails” escalation packet (what to hand to IT/SRE)

• Output of wsl --status and wsl -l -v
• Output of systeminfo.exe Hyper-V Requirements block
• Output of DISM feature checks for WSL and VM platform
• Last 20 events from LxssManager operational log
• Whether Store access is allowed and whether a proxy is enforced
• Whether %UserProfile%\.wslconfig exists and contains a custom kernel path

FAQ

1) Do I need to update Ubuntu packages to fix “WSL kernel update required”?

No. This error is about the WSL2 kernel and host-side components. Updating the distro can be healthy, but it won’t install the missing kernel.

2) Why does this happen after Docker Desktop updates?

Because Docker Desktop uses WSL2 as a backend on many systems. If Docker expects WSL features provided by a newer WSL/kernel combo, it will surface the mismatch immediately.

3) Can I just switch to WSL1 and move on?

Sometimes. WSL1 can be a tactical workaround if you only need a shell and file tools. But Docker and many modern workflows assume WSL2. Treat WSL1 as containment, not a long-term plan.

4) I ran wsl --update and it says “Update successful,” but it still fails. Now what?

Run wsl --shutdown, reboot if you recently enabled features, and check %UserProfile%\.wslconfig for a custom kernel path. Also inspect LxssManager event logs for a more specific error code.

5) What does it mean if wsl --version is not recognized?

You’re likely on an older WSL distribution model where version reporting isn’t available that way. You can still use wsl --status (if present) and Windows feature checks. Updating WSL via your allowed channel is usually the move.

6) Will reinstalling WSL delete my Linux files?

It can, depending on what you uninstall/reset. Unregistering a distro removes its filesystem. Don’t do that as a first response. Fix the host/kernel mismatch first.

7) Why does only one distro fail but others run?

If a particular distro is misconfigured or corrupted, it can fail independently. But if the error is “kernel update required,” suspect host/kernel mismatch first, then look at per-distro issues.

8) Is this a security issue?

Usually no—it’s a lifecycle/patch alignment issue. But it can be triggered by security hardening that changes virtualization availability or blocks update channels.

9) Do I need Hyper-V enabled?

WSL2 relies on Windows’ virtualization stack. You don’t necessarily need the full Hyper-V role as used for server workloads, but you do need virtualization support and the Virtual Machine Platform feature.

10) What’s the cleanest way to avoid this recurring?

Keep Windows build, WSL version, and Docker Desktop (if used) aligned via a tested update ring. Also avoid unmanaged custom kernel overrides unless you intend to own that maintenance.

Next steps you can actually do today

Fixing “WSL kernel update required” cleanly is less about heroics and more about refusing to guess. Get the state (wsl --status), update the component that’s actually wrong (wsl --update or your enterprise channel), and verify the platform can boot virtualization (systeminfo.exe + DISM feature checks).

If you’re supporting more than your own laptop, go one step further: standardize a compatibility set and roll it out deliberately. WSL isn’t “just a dev tool” once it’s the foundation for local builds and container workflows. It’s part of production, even if it runs under someone’s desk.

Practical next actions:

• Run the Fast diagnosis playbook on one broken machine and one working machine; diff the outputs.
• Remove accidental custom kernel overrides in .wslconfig unless they’re intentionally managed.
• Build a small preflight script for virtualization + feature + version checks, and run it at provisioning time.
• Stop telling people to reinstall Ubuntu for host kernel problems. That’s how you lose data and trust at the same time.