When WSL isn’t working in Windows 11, you usually see a numbered error such as “0x80370102”, “0x8007019e”, or “0x800701bc”, or an Ubuntu window that flashes open and closes. These codes usually point to a missing feature, a virtualization setting, a kernel component, or a damaged installation, so run Fix #1 first and then use the quick reference table to jump to your exact error.
Fix #1: Run wsl –update and wsl –status First
WSL depends on four things working together. Those are hardware virtualization, the Virtual Machine Platform feature, the Windows Subsystem for Linux feature, and a Linux kernel that updates separately from Windows. An outdated or half-installed WSL is a common cause, and the commands below give you a quick first status check. They won’t diagnose every dependency, such as firmware virtualization or policy restrictions, but they narrow things down.
- Click Start, type
PowerShell, right-click Windows PowerShell (or Terminal), and choose Run as administrator. - Run
wsl --updateto pull the latest WSL and kernel components. You should see either an “up to date” message or a download and install progress line.
- If the update fails or stalls on a PC where the Microsoft Store is blocked, run
wsl --update --web-downloadinstead. That flag downloads the update directly instead of going through the Store. - Run
wsl --statusto see your default distribution and default WSL version.
- Run
wsl --list --verboseto see every installed distro, whether it’s running, and whether it uses WSL 1 or WSL 2.
- If
wsl --statuscomplains that WSL isn’t installed, checkwsl --list --verbosefirst so you know whether any distro already exists. Then, on a supported Windows 11 build and from an administrator window, runwsl --installand restart Windows when prompted. It enables the required Windows features and, if no distro is installed, installs Ubuntu by default.
Verify: Launch your distro from the Start menu. If it opens to a Linux prompt, you’re done. If it throws an error code, match it in the table below.
Microsoft’s install guide and basic commands reference cover every flag used here. For a deeper look at version output, see our guide on how to check your WSL version.
WSL Error Code Quick Reference
| Error or symptom | What it usually means | Go to |
|---|---|---|
| Distro window opens and closes instantly | Stuck or crashed WSL process | Fix #2 |
| “0x800701bc” / “WSL 2 requires an update to its kernel component” | WSL 2 kernel missing or outdated | Fix #3 |
| “0x8007019e” / “optional component is not enabled” | Windows Subsystem for Linux feature is off or incomplete | Fix #4 |
| “0x80370102” / “The virtual machine could not be started” | Virtualization off in firmware, or Virtual Machine Platform off | Fix #5 |
| “wsl” is not recognized, or WSL vanished after an update | Disabled feature, PATH issue, or damaged installation | Fix #6 |
| Distro stuck on “Installing…” | Download or registration step stuck | Fix #7 |
| Distro still broken after all of the above | Corrupted distro files | Fix #8 |
| “0x800704ec” | Can indicate an organization policy restriction | Work or school PC section |
Fix #2: Restart WSL With wsl –shutdown (Window Opens and Closes Instantly)
Symptoms:
- The Ubuntu (or other distro) window flashes and closes.
- The terminal hangs on a blank screen and never shows a prompt.
Why it happens: This often means a stuck or failed distro process in the background, and closing the window doesn’t stop it. If it keeps happening after this fix, note the exact error text in the terminal and match it in the table above.
- Open PowerShell (admin rights aren’t needed for this one).
- Run
wsl --shutdownto stop every running distro and the WSL 2 virtual machine. - Wait about 10 seconds.
- Relaunch your distro from the Start menu, or run
wsl -d Ubuntu(swap in your distro name fromwsl --list --verbose). - If the window still closes, check the default version with
wsl --status. Runwsl --set-default-version 2if it shows 1 and you expected WSL 2.
Verify: wsl --list --verbose should show your distro as Running after you launch it.
I’d try this before anything else that touches Windows features. It’s harmless and takes seconds.
Fix #3: Update the WSL 2 Kernel (Error 0x800701bc)
Symptoms:
- The message typically reads “WSL 2 requires an update to its kernel component.”
- The error code “0x800701bc” appears when you start or convert a distro to WSL 2.
Why it happens: Error 0x800701bc indicates the WSL 2 kernel component is missing or needs updating. wsl --update supplies the current component. If wsl --update itself won’t run on an older or manually installed setup, Microsoft’s WSL troubleshooting page describes a manual kernel update package as the fallback.
- Open PowerShell as administrator.
- Run
wsl --update. - If that fails or never finishes, run
wsl --update --web-download. - Run
wsl --shutdownso the new kernel loads on the next start. - Relaunch your distro.
Verify: wsl --status runs without the kernel warning, and your distro opens normally. Kernel changes are listed in Microsoft’s WSL kernel release notes.
Fix #4: Turn On the Windows Subsystem for Linux Feature (Error 0x8007019e)
Symptoms:
- An error along the lines of “WslRegisterDistribution failed with error: 0x8007019e.”
- A message saying the Windows Subsystem for Linux optional component isn’t enabled.
Why it happens: The Microsoft-Windows-Subsystem-Linux optional feature may be disabled, or the installation may be incomplete. Check both required features below.
- Press
Win + R, typeoptionalfeatures.exe, and pressEnter. You can also search Start for Turn Windows features on or off. - Check Windows Subsystem for Linux.
- Check Virtual Machine Platform while you’re here, since WSL 2 needs both.
- Click OK and let Windows install the files.
- Restart your PC.
The fast path from an elevated PowerShell window does the same job:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Restart after both commands finish. Settings also links to this dialog through Optional features > More Windows features. Whether that sits under System or Apps depends on your Windows 11 build, so the Start search is the more reliable route.
Verify: wsl --status returns your default version instead of the component error.
Fix #5: Enable Virtualization and Virtual Machine Platform (Error 0x80370102)
Symptoms:
- “WslRegisterDistribution failed with error: 0x80370102.”
- Text similar to “The virtual machine could not be started because a required feature is not installed.”
Why it happens: This code is commonly caused by one of two things. Either hardware virtualization is disabled in your PC’s UEFI/BIOS, or the Virtual Machine Platform feature is turned off. WSL 2 can’t start its lightweight VM without both.
- Press
Ctrl + Shift + Escto open Task Manager. - Click Performance, then CPU.
- Look for Virtualization in the lower-right details panel.
- If it says Disabled, you need to turn it on in your UEFI/BIOS. Menu names vary by manufacturer, so follow our guide on how to check if virtualization is enabled on Windows 11 and come back here.
- If it says Enabled, turn on Virtual Machine Platform using the Windows Features steps in Fix #4, or run this in an elevated PowerShell window:
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
- Restart Windows.
Verify: Task Manager shows Virtualization: Enabled, and your distro launches. WSL 2 needs hardware virtualization, or a virtual machine configured for nested virtualization. If neither is available, WSL 1 may still work for some tasks (wsl --set-version Ubuntu 1). Otherwise the hardware or hosting environment has to change.
Fix #6: Re-enable WSL After a Windows Update (‘wsl’ Is Not Recognized)
Symptoms:
- PowerShell says “The term ‘wsl’ is not recognized” or Command Prompt says “‘wsl’ is not recognized as an internal or external command.”
- Your distro disappeared from Start after a major Windows feature update.
Why it happens: A major Windows update can reset or disable the Windows Subsystem for Linux optional component. The same message can also show up when the wsl.exe path isn’t registered correctly after an update, or, less commonly, when the Windows installation itself is in a damaged state that a simple feature toggle won’t fix.
- Repeat Fix #4 to recheck Windows Subsystem for Linux and Virtual Machine Platform.
- Restart Windows.
- Before changing anything else, run
wsl --list --verboseto note which distros are currently installed, and back up any distro holding files you care about using the export steps in Fix #8. - If
wslstill isn’t recognized, open PowerShell as administrator and runwsl --install. - Restart again when prompted.
wsl --install is an installation command rather than a dedicated repair tool, so treat it as an attempted fix rather than a guaranteed one. In most cases it re-enables the missing components without disturbing an already-installed distro’s data, but on a PC with unusual installation state, distro registration, or Group Policy restrictions, its behavior can be less predictable.
After restarting, compare wsl --list --verbose against the list you recorded in step 3. If a distro is missing or won’t start, restore it from the backup you made. If wsl is still not recognized at this point, the issue may sit with the Windows installation itself, which typically needs a DISM/SFC repair or an in-place upgrade rather than another round of WSL commands.
Verify: wsl --list --verbose lists your existing distros again, matching what you recorded in step 3.
Fix #7: Reinstall a Distro Stuck on “Installing…”
Symptoms:
- The first-run window sits on “Installing, this may take a few minutes…” forever.
- The Store download never completes.
Why it happens: The download, registration, or first-run setup step can stall, and Store delivery problems are one trigger. Microsoft documents the --web-download route below specifically for installs that hang at 0.0%. It’s worth trying for other stuck installs too, but it isn’t guaranteed to fix registration or filesystem problems.
- Close the stuck window.
- Run
wsl --shutdown. - Run
wsl --list --onlineto get the exact distro name, such asUbuntuorDebian. - Run
wsl --install --web-download -d Ubuntu, replacingUbuntuwith your distro name. - Create your Linux username and password when the first-run prompt appears.
Verify: wsl --list --verbose shows the distro with version 2.
If a distro still won’t start after this, you can try Settings > Apps > Installed apps, click the three dots next to the distro, open Advanced options, and click Reset. Treat Reset as destructive. Back up with wsl --export (see Fix #8) first if the distro holds anything you care about.
Fix #8: Back Up, Unregister, and Reinstall a Broken Distro
Use this only when Fixes #1 through #7 haven’t helped and the distro’s files are corrupted.
Warning:
wsl --unregisterpermanently deletes the distro and every file inside it, including your home folder. Don’t skip the export step.
- Run
wsl --shutdown. - Export a backup. Swap in your distro name and a path with plenty of free space:
wsl --export Ubuntu D:\Backups\ubuntu-backup.tar
- Confirm the
.tarfile exists and isn’t 0 bytes. Copying it to an external SSD is cheap insurance. - Unregister the broken distro:
wsl --unregister Ubuntu
- Reinstall a fresh copy with
wsl --install -d Ubuntu. - If you’d rather restore your old environment than start clean, import the backup instead of step 5:
wsl --import Ubuntu D:\WSL\Ubuntu D:\Backups\ubuntu-backup.tar
An imported distro can log you in as root. To fix that, make sure your normal Linux user exists inside the distro, then add these lines to /etc/wsl.conf, replacing yourusername:
[user]
default=yourusername
This is the [user] section’s default key from Microsoft’s configuration table (some Microsoft pages write the same setting as user.default). Run wsl --shutdown and relaunch the distro. The options are described in Microsoft’s WSL config docs.
Verify: wsl --list --verbose shows the distro, and your files are where you left them. Once it works, our guide on how to move a WSL distro to another drive uses the same export/import pattern if C: is filling up.
Is It WSL or a Work or School PC Policy?
If you see “0x800704ec” on a work or school PC, the code can indicate an organization policy or security control restricting WSL. Microsoft’s WSL FAQ covers managing WSL in enterprise settings. Run wsl --update once to rule out a version issue. If the error stays and the device is managed by your organization, contact your IT administrator, since policy restrictions usually can’t be changed from a standard account.
Other signs you’re dealing with a managed PC are a blocked Microsoft Store and settings marked as managed by your organization. Networking problems, like no internet inside WSL when you’re on a VPN, are a separate topic. Those usually involve the networkingMode setting in .wslconfig, and corporate VPNs often need IT involvement.
Configuration Mistakes to Check
- Wrong default version:
wsl --statusshows version 1 when your tutorial assumes WSL 2. Fix it withwsl --set-default-version 2for new distros, orwsl --set-version Ubuntu 2for an existing one. - Editing the wrong config file: Global WSL 2 settings live in
%UserProfile%\.wslconfigon the Windows side. Per-distro settings live in/etc/wsl.confinside Linux. Putting a setting in the wrong file means it’s silently ignored. - Not restarting after config changes: WSL only reads both files at startup. Run
wsl --shutdown, then relaunch. - Wrong distro name: Commands like
wsl --exportneed the exact name fromwsl --list --verbose, including capitalization and version suffixes.
Getting Help
When nothing above works, gather this before you ask anyone:
- The full output of
wsl --statusandwsl --list --verbose. - The exact error text and code, copied from the terminal.
- Your Windows 11 version from Settings > System > About.
- For hangs, open Task Manager’s Details tab, right-click vmmemWSL, and choose Create memory dump file.
Then check Microsoft’s WSL troubleshooting guide and search the Microsoft/WSL GitHub issues. The WSL team tracks bugs there, and someone has often already posted a workaround for your error code.
Prevention Tips
- Update WSL on a schedule: Run
wsl --updateevery month or so. It’s independent of Windows Update. - Recheck features after big Windows updates: A quick
wsl --statusafter a feature update catches a disabled component before a deadline does. - Keep a current export: A monthly
wsl --exportto a portable hard drive turns Fix #8 into a 10-minute job instead of a lost weekend. - Leave virtualization on: Some BIOS updates reset firmware settings. If 0x80370102 suddenly comes back after a firmware update, check Task Manager first.
- Watch memory use: WSL 2 shares your PC’s RAM. If distros get slow or unstable on an 8GB laptop, a RAM upgrade helps more than any setting.
Wrapping Up
wsl --update followed by wsl --shutdown is a sensible low-risk first step for update-related and stuck-process problems, and I’d always run those before touching Windows Features or firmware. If 0x80370102 keeps returning even with virtualization enabled, recheck Virtual Machine Platform and, inside a VM, nested virtualization. A BIOS update that reset firmware settings is another possibility worth ruling out. If distros keep corrupting after clean reinstalls and you see disk errors or storage warnings in Event Viewer, back up your exports and check the drive’s health.
| Recommended action | Applies To |
|---|---|
wsl --update, wsl --status | Every WSL error |
wsl --shutdown | Window closes instantly, hangs |
wsl --update --web-download | 0x800701bc, blocked Store |
| Enable Windows Subsystem for Linux | 0x8007019e, “wsl” not recognized |
| Enable virtualization and Virtual Machine Platform | 0x80370102 |
wsl --install --web-download -d Ubuntu | Stuck on “Installing…” |
wsl --export, then wsl --unregister | Corrupted distro |
| Contact IT | 0x800704ec on a managed PC |
For rollback safety, make wsl --export a habit before any major change. A known-good .tar file means every fix in this list is reversible.
Last updated: 2026-11-15 | Applies to WSL on supported Windows 11 builds with hardware virtualization available | Sources: Microsoft Learn WSL documentation, retrieved 2026-11-15