How to Install WSL 2 and Ubuntu on Windows 11 Safely

To install WSL on Windows 11, open PowerShell as administrator, run wsl --install, and restart. That one command, documented on Microsoft Learn, turns on the Windows Subsystem for Linux and Virtual Machine Platform features, installs the WSL 2 Linux kernel, sets WSL 2 as the default and installs Ubuntu. Windows 10 works too from version 2004 (build 19041).

The security work comes after. Create a normal Linux user with a real password on first launch, run wsl --update and sudo apt update && sudo apt upgrade straight away, and decide how much of Windows your distro should see: your C: drive, Windows programs, your network and your firewall rules. Get WSL and every distro only from Microsoft, the microsoft/WSL GitHub releases page or the distro publisher.

Every command below comes from Microsoft Learn's WSL documentation or Canonical's Ubuntu on WSL documentation, fetched on 23 October 2026. Each page is linked in the Sources list.

Key takeaways

• One command for most people. wsl --install in an elevated PowerShell, then reboot. Use wsl --list --online and wsl --install -d with a name for a distro other than Ubuntu.
• Official sources only. WSL comes from the Microsoft Store or github.com/microsoft/WSL/releases. Ubuntu comes from the Store, wsl --install or releases.ubuntu.com.
• Verify offline downloads. Compare Get-FileHash with the SHA256 digest GitHub lists for each WSL release file, and check Ubuntu .wsl images against its GPG signed SHA256SUMS.
• Your Linux user can run sudo. Give it a real password and never make root the default user.
• Windows does not patch your distro. wsl --update updates WSL; you update Linux packages yourself.
• WSL shares a lot with Windows. Drives mount under /mnt, Windows programs run from Linux, and Windows paths join $PATH. Each can be turned off in /etc/wsl.conf.
• Firewall rules follow you in on Windows 11 22H2 and later with WSL 2.0.9 or later, through Hyper-V firewall.

What is WSL 2, and what does wsl --install actually do?

The Windows Subsystem for Linux runs a Linux distribution such as Ubuntu, Debian, openSUSE, Kali or Arch Linux on Windows, with Linux tools running unmodified, without a traditional virtual machine or dual boot.

WSL 1 translates Linux system calls. WSL 2, the default for every new install, runs a real Linux kernel inside what Microsoft calls a lightweight utility virtual machine. Microsoft's overview page is specific: distributions run as isolated containers inside that one managed VM. They share the network namespace, device tree (other than /dev/pts), CPU, kernel, memory, swap and /init binary, but each has its own PID, mount, user and cgroup namespaces and its own init process.

So two distros on one PC are not two separate VMs. They share a kernel and a network namespace. Our post on what WSL 2 isolates and what it shares walks through Microsoft's wording in detail.

Microsoft's "Set up a WSL development environment" guide lists what wsl --install does:

1. Enables the optional WSL and Virtual Machine Platform components.
2. Downloads and installs the latest Linux kernel.
3. Sets WSL 2 as the default.
4. Downloads and installs Ubuntu. A reboot may be required.

The kernel is built by Microsoft from the latest stable branch at kernel.org and tuned for WSL 2, according to Microsoft's WSL 1 versus WSL 2 comparison. WSL itself is open source: Microsoft's open source page points to microsoft/WSL on GitHub, with the kernel in microsoft/WSL2-Linux-Kernel and graphical app support in microsoft/wslg. A few parts remain closed and ship inside Windows, including Lxcore.sys (the WSL 1 driver) and the components behind the \\wsl.localhost file share.

The names you will see in process lists and errors are wsl.exe, wslconfig.exe and wslg.exe (the command line entry points) and wslservice.exe (the service that starts the VM and distros). Microsoft's FAQ notes LxssManager was replaced by WSLService when WSL moved from an inbox Windows component to the Microsoft Store.

Requirements: Windows 11 vs Windows 10

Any current Windows 11 PC with virtualization switched on runs WSL 2. Windows 10 needs a recent enough build.

Canonical's Ubuntu on WSL guide is slightly stricter: it recommends Windows 11 and lists Windows 10 version 21H2 as the minimum, on a physical machine. For a fleet running Ubuntu, use Canonical's floor.

Several features are Windows 11 only. Microsoft's advanced settings page marks networkingMode, firewall and dnsTunneling as needing Windows 11 22H2 or higher, and autoProxy as Windows 11 only. Windows 10 machines get WSL 2 but not the networking and firewall integration described later.

Check your build and virtualization

Press Windows key + R, type winver and select OK, or open Settings > System > About and read OS build and System type. On Windows Server, Microsoft's troubleshooting page gives:

systeminfo | Select-String "^OS Name","^OS Version"

WSL 2 needs hardware virtualization switched on in UEFI or BIOS, and a CPU with Second Level Address Translation. Microsoft says SLAT arrived with Intel Nehalem (first generation Core) and AMD Opteron, so a Core 2 Duo cannot run WSL 2 even if Virtual Machine Platform installs. Microsoft's support article "Enable virtualization on Windows" covers the firmware setting, which differs by PC maker.

Installing WSL inside a VM needs nested virtualization. Microsoft documents this for a Hyper-V host, run as administrator on the host:

Set-VMProcessor -VMName <VMName> -ExposeVirtualizationExtensions $true

Canonical does not recommend following its tutorial inside a Windows VM, and Microsoft notes nested virtualization is not supported on Azure VMs with Trusted Launch.

Which install route should you use?

All of these routes are documented by Microsoft or Canonical.

For a personal or developer machine, the first row is the answer.

Step by step: install WSL 2 and Ubuntu on Windows 11

Step 1: open PowerShell as administrator

Right-click Start or search for PowerShell, and choose Run as administrator. Microsoft's install page requires administrator mode because the command enables Windows features.

Step 2: see which distros are available (optional)

wsl --list --online

The short form is wsl -l -o. Canonical's guide shows names such as Ubuntu, Ubuntu-26.04, Ubuntu-24.04 and Ubuntu-22.04 alongside other publishers' distros. Plain Ubuntu tracks the latest LTS, which Canonical says is currently 26.04 LTS. A numbered name stays on that release until you upgrade it.

Step 3: install

wsl --install

Or, for a specific distro by NAME:

wsl --install -d Ubuntu-24.04

Useful options from Microsoft's command reference: --no-launch installs without starting the distro, --web-download installs from an online source instead of the Store, --location picks the install folder, and --no-distribution installs WSL alone, for when you plan to import an approved image.

Microsoft notes wsl --install only does the full setup when WSL is not installed at all. If you get the help text instead, WSL is already present, so use wsl --list --online and wsl --install -d.

Step 4: restart

Restart when prompted. Canonical notes that if the components were already enabled, a reboot may not be needed and the distro install starts straight away.

Step 5: first launch

The first launch decompresses files for a minute or two, then asks for a Linux user name and password. The first-run section below covers this; do not close the window early.

Step 6: confirm it is WSL 2

wsl --list --verbose

wsl -l -v lists each distro, whether it is running and its WSL version. If an older distro shows 1, convert it, and set WSL 2 as the default for new installs:

wsl --set-version Ubuntu 2
wsl --set-default-version 2

Microsoft warns conversion can be slow or fail on large distros, so back up first.

Step 7: check the WSL version

wsl --version
wsl --status

wsl --version shows WSL and component versions, including the kernel. wsl --status shows the default distro and version. Microsoft's enterprise guidance treats WSL 2.0.9 as a floor.

To open a distro afterwards, use Windows Terminal (Microsoft's recommendation), the Start menu, wsl for the default distro, or wsl --distribution Ubuntu-24.04 for a specific one. wsl ~ starts in your Linux home directory. From inside Linux, type wsl.exe rather than wsl.

The manual route for older Windows 10 builds

For builds that cannot run wsl --install, and for Server Core, Microsoft keeps manual steps. In an elevated PowerShell:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Restart, install the WSL 2 Linux kernel update package from the x64 or Arm64 link on Microsoft's manual installation page, run wsl --set-default-version 2, then install a distro. Microsoft notes this kernel package updates less often than the Store version, so move to wsl --update once the build allows it. To confirm the feature is on:

Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

Offline install

Microsoft's install page gives three steps: install the latest WSL MSI from the microsoft/WSL GitHub releases page; enable Virtual Machine Platform with the second dism.exe command above and restart; then install a distro from a .wsl file, whose URLs Microsoft says are listed in DistributionInfo.json in the microsoft/WSL repository.

For Ubuntu, Canonical publishes .wsl images on releases.ubuntu.com (for 26.04 LTS, Resolute Raccoon, that is releases.ubuntu.com/resolute). Double-click the image, or run this in the download folder:

wsl --install --from-file ubuntu-26.04.1-wsl-amd64.wsl

Canonical says this needs no Store access, the images can be hosted on an internal network, and the tar based format needs WSL 2.4.10 or later. Verify the file first, as shown next.

Where WSL and distros come from, and how to check you have the real ones

WSL is a heavily searched term, which attracts lookalike download pages, "WSL installer" executables and bundled repacks. WSL is free and built into Windows, so there is no reason to get it anywhere except Microsoft.

wsl --list --online is the safest way to choose a distro, because the list comes from Microsoft's distribution manifest rather than a search result. In the Store, read the publisher. Microsoft's own manual install page mixes official and community builds and labels some "(Unofficial)" or "(Paid)". Unofficial does not mean malicious, but it means someone other than the distro project maintains it.

Verify a WSL MSI from GitHub

GitHub's release data for microsoft/WSL lists a SHA256 digest for every asset. Release 3.0.3 (9 October 2026), for example, ships wsl.3.0.3.0.x64.msi, wsl.3.0.3.0.arm64.msi, an .msixbundle and a containers NuGet package, each with its own digest. In the download folder:

Get-FileHash .\wsl.3.0.3.0.x64.msi
Get-AuthenticodeSignature .\wsl.3.0.3.0.x64.msi

Get-FileHash uses SHA256 by default, per Microsoft's documentation; compare its output with the digest on the release and delete the file if they differ. Get-AuthenticodeSignature reports the file's Authenticode signature: check the status is valid and read who the signing certificate was issued to before running it. A hash proves the file matches what was published; a signature tells you who published it. Our post on checksums versus signatures explains why you want both.

Pick a stable release. The page mixes stable builds and pre-releases: on 23 October 2026, 3.0.4 (20 October) was a pre-release and 3.0.3 was the newest stable build.

Verify an Ubuntu .wsl image

Canonical lists its WSL images in the release's SHA256SUMS file, signed in SHA256SUMS.gpg. On 23 October 2026 the 26.04 folder's SHA256SUMS included both ubuntu-26.04-wsl-amd64.wsl and ubuntu-26.04.1-wsl-amd64.wsl. On Windows, hash the image and compare it with its line:

Get-FileHash .\ubuntu-26.04.1-wsl-amd64.wsl

To check the signature on the checksum file too, Ubuntu's "How to verify your Ubuntu download" tutorial gives these commands for any Linux shell, including an existing WSL distro:

gpg --keyid-format long --keyserver hkp://keyserver.ubuntu.com --recv-keys 0x46181433FBB75451 0xD94AA3F0EFE21092
gpg --keyid-format long --list-keys --with-fingerprint 0x46181433FBB75451 0xD94AA3F0EFE21092
gpg --keyid-format long --verify SHA256SUMS.gpg SHA256SUMS
sha256sum -c SHA256SUMS 2>&1 | grep OK

You want a good signature from "Ubuntu CD Image Automatic Signing Key". When we inspected the 26.04 SHA256SUMS.gpg on 23 October 2026, it was signed by key D94AA3F0EFE21092, fingerprint 8439 38DF 228D 22F7 B374 2BC0 D94A A3F0 EFE2 1092. Compare the full fingerprint with Ubuntu's tutorial, not just the short ID. The warning that the key "is not certified with a trusted signature" is normal unless you maintain a web of trust.

For Store and wsl --install installs there is no published hash to check by hand. Your job there is to install from the real publisher's listing.

First run: create your Linux user and do not live as root

Microsoft's environment setup guide answers most first-run questions:

• The user name and password belong to that distro only and have no link to your Windows account.
• Nothing appears while you type the password. That is normal.
• The account becomes the default user and signs in automatically.
• The account is the Linux administrator and can run sudo.
• Each distro has its own accounts; you create one again after every add, reinstall or reset.
• Distros are per Windows user and cannot be shared with other Windows accounts.

Anyone who can run commands as your Windows user can open your distro, and inside it you have sudo. The password prompt is the only thing between a pasted script and root, so make it a real password.

Do not make root the default user

Plenty of guides suggest running as root to "fix" permission errors. Don't. Microsoft documents wsl -u root (or wsl -d Ubuntu-24.04 -u root) for one narrow job: resetting a forgotten Linux password with passwd and your user name, then exit. To change your own password while signed in, run passwd.

To make another existing user the default on a Store installed distro, Microsoft documents ubuntu config --default-user johndoe. That does not work for imported distros; set the default in /etc/wsl.conf instead:

[user]
default=johndoe

Update packages straight away

The image you installed was built weeks or months ago. Microsoft's setup guide gives this for Ubuntu and Debian:

sudo apt update && sudo apt upgrade

Its next sentence is the one people miss: Windows does not automatically update or upgrade your Linux distributions. For unattended security updates inside Ubuntu, set them up as you would on a server; see how to enable unattended upgrades on Ubuntu.

If you need services such as SSH or a database, Microsoft says the Store version supports systemd once you add [boot] with systemd=true to /etc/wsl.conf and restart WSL with wsl.exe --shutdown. Only enable it if you need it; every running service is one more thing to patch.

What WSL shares with Windows, and how to narrow it

Microsoft's FAQ is candid about how WSL differs from a regular VM. Users have full access to their Linux instances and the VM's lifetime; WSL automatically gives access to Windows files; Windows paths are added to $PATH by default; Linux can run Windows executables; and the kernel updates automatically. Each is a deliberate convenience. Keep the ones you use and turn off the rest.

The file system bridge

Windows fixed drives mount automatically under /mnt, so C:\ is /mnt/c. Windows apps reach Linux files through \\wsl$ (also \\wsl.localhost).

Microsoft's enterprise page explains the permission model. A Linux program touching a Windows file does so with the permissions of the Windows user who ran wsl.exe. Root inside Linux does not grant Windows administrator rights; running bash has the same security level as running powershell as that user. The flip side: anything your Windows account can read or write, a Linux process you start can too, including documents, browser profile folders and SSH keys on the Windows side.

From Microsoft's file permissions page:

• Windows files under /mnt/c show permissions calculated from your Windows user's effective rights. Read-only in Windows stays read-only in Linux.
• Linux permission metadata on Windows files is off by default. Even with it on, chmod 777 cannot give you more access than Windows allows.
• Windows apps using \\wsl$ act as the distro's default user, and new files get a umask of 022.

Keep Linux projects in the Linux file system (~/project), which Microsoft also recommends for speed. If a distro does not need your Windows drives at all, stop mounting them:

[automount]
enabled=false

Microsoft notes drives can still be mounted by hand or through fstab.

The program bridge (interop)

From WSL you can run any Windows program, which is how notepad.exe, explorer.exe . and code . work. Two /etc/wsl.conf keys control it:

[interop]
enabled=false
appendWindowsPath=false

enabled decides whether WSL can launch Windows processes at all; appendWindowsPath decides whether Windows path entries join Linux $PATH. Turning interop off makes a distro behave more like a separate Linux box but breaks those conveniences. A sensible middle ground for many developers is to keep interop on and set only appendWindowsPath=false, so a Linux command never silently resolves to a Windows binary of the same name.

Changes to wsl.conf apply only once the distro fully stops. Microsoft calls this the 8 second rule: wait about 8 seconds after closing every shell, or run wsl --shutdown (all distros) or wsl --terminate Ubuntu-24.04 (one).

The network bridge

By default WSL 2 uses NAT. From Windows, localhost reaches a server in Linux; from the LAN, nothing in WSL 2 is reachable by default because the VM has its own virtual adapter. Microsoft's networking page warns that binding an app to 0.0.0.0 instead of 127.0.0.1 allows connections from your LAN, and its netsh interface portproxy example for exposing a port uses listenaddress=0.0.0.0, which accepts requests from any IP address. Use either only when you mean it.

On Windows 11 22H2 and later, %UserProfile%\.wslconfig can switch to mirrored mode with networkingMode=mirrored under [wsl2]. Microsoft lists its benefits as IPv6, reaching Windows servers at 127.0.0.1, better VPN compatibility, multicast, and connecting to WSL directly from your LAN. That last one changes your exposure, and in mirrored mode inbound traffic is governed by the Hyper-V firewall. Microsoft also documents dnsTunneling (on by default on Windows 11 22H2 and later) and autoProxy (use the Windows HTTP proxy), and its enterprise page recommends all three for corporate networks.

The firewall: Hyper-V firewall and WSL

On Windows 11 22H2 and later with WSL 2.0.9 and later, Microsoft says Hyper-V firewall is on by default for WSL, and Windows firewall rules set on the host apply to all WSL distros automatically. The .wslconfig key firewall defaults to true; leave it there.

Microsoft's "Configure Hyper-V firewall" page shows how to check it, using WSL's fixed VMCreatorId. In an elevated PowerShell:

Get-NetFirewallHyperVVMCreator
Get-NetFirewallHyperVVMSetting -PolicyStore ActiveStore -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}'
Get-NetFirewallHyperVRule -VMCreatorId '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}'

The second command shows whether Hyper-V firewall is enabled for WSL, the default inbound and outbound actions, whether host to WSL loopback is allowed, and how host and enterprise policy merge.

To accept inbound connections, Microsoft documents a broad option and a narrow one:

# Broad: every listening service in every distro
Set-NetFirewallHyperVVMSetting -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -DefaultInboundAction Allow

# Narrow: one named rule for one port
New-NetFirewallHyperVRule -Name "MyWebServer" -DisplayName "My Web Server" -Direction Inbound -VMCreatorId '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -Protocol TCP -LocalPorts 80

Prefer the named rule. It is easy to audit and easy to remove. Microsoft also notes Hyper-V firewall cannot be configured through group policy; if Windows Firewall is managed by GPO and Hyper-V firewall is not configured through a CSP, the GPO rules are mirrored automatically.

Hardening settings at a glance

Enterprise controls: Intune, group policy and Defender

Microsoft's enterprise page recommends three things for companies allowing WSL: Microsoft Defender for Endpoint, Intune settings, and the networking and firewall integration above, on Windows 10 22H2 or Windows 11 22H2 or later with WSL 2.0.9 or later.

In the Intune admin center, Microsoft's path is Devices, Configuration Profiles, Create, New Policy, Windows 10 and later, Settings catalog, then a search for "Windows Subsystem for Linux". Microsoft recommends setting these to Disabled:

The full list adds "Allow the Windows Subsystem For Linux" (switch WSL off for everyone on the machine) and "Allow passthrough disk mount" (blocks wsl --mount). Most of these apply only to the Store version, one more reason to disable the inbox version. For group policy, Microsoft publishes a WSL ADMX file on GitHub.

Microsoft says Defender for Endpoint integrates with WSL through a plug-in so security teams can monitor security events inside running distros. For standard images, its supported approach is to build a distro, wsl --export it, share it internally and wsl --import it on each machine.

Read Microsoft's list of what is not supported yet before writing a WSL policy:

• Managing updates and patching of Linux distros and packages with Windows tools.
• Having Windows Update also update distro contents.
• Controlling which distributions users can access.
• Controlling root access for users.

You can control whether WSL runs, which version and how it is configured, but not the Linux user space. Microsoft strongly recommends Linux configuration management tools for that.

How to keep WSL and your distros patched

Microsoft's troubleshooting page names the two things to update: WSL itself, and each distro's packages.

Update WSL

wsl --update
wsl --version

Add --web-download to fetch the update from GitHub rather than the Store. The Store version gets updates as they are released; the inbox version gets them through Windows Update, which is why Microsoft's command reference recommends the Store version.

WSL ships often. Since 11 September 2026 the microsoft/WSL releases page shows stable releases 2.7.14, 3.0.1 (29 September, which made WSL containers generally available) and 3.0.3 (9 October), with pre-releases between them; 3.0.3 updated the bundled kernel to 6.18.54.1. We covered the changes in the WSL 3.0 release hardening notes. wsl --update --pre-release installs preview builds without joining Windows Insider; keep it off machines that matter.

Update the distro

Inside each distro:

sudo apt update && sudo apt upgrade

Microsoft's troubleshooting page writes this step as apt-get update | apt-get upgrade. Use the && form from its setup guide, which runs the upgrade only after the package lists refresh successfully. Keep Ubuntu's default package sources unless you have a reason to add one, and treat any guide that pipes a script into sudo bash with the caution you would on a server.

Canonical's distributions page says numbered LTS releases on WSL get five years of standard support, interim releases are not supported on WSL, and the plain Ubuntu app tracks the latest LTS and can move to a new LTS once its first point release is out. Check your release with wsl -l -v and move off it before its support ends.

Patch what you build inside WSL

The distro is only the base. Runtimes, package managers and project dependencies you install inside WSL are not updated by apt unless apt installed them. Our guides to Node.js and npm, Python and pip, Git and Docker cover the next step; their Linux sections apply inside WSL.

How to back up, move and remove WSL distros

Back up and restore

Microsoft's FAQ calls export and import the best way to back up or move a distro:

wsl --export Ubuntu-24.04 D:\Backups\ubuntu-2404.tar
wsl --import Ubuntu-Restored D:\WSL\Ubuntu-Restored D:\Backups\ubuntu-2404.tar

Export defaults to tar; --vhd exports a .vhdx on WSL 2. On import, --version 2 forces WSL 2, and wsl --import-in-place registers an existing ext4 .vhdx where it sits.

Treat an export as sensitive. It holds everything in the distro, including shell history, SSH keys and cached cloud tokens. Store it encrypted and delete old copies.

Move a distro to another drive

Microsoft's FAQ gives this sequence:

wsl --export Ubuntu D:\WSLDistros\Ubuntu\ext4.vhdx --vhd
wsl --unregister Ubuntu
wsl --import-in-place Ubuntu D:\WSLDistros\Ubuntu\ext4.vhdx

The FAQ writes the export flag as --format vhd, while the command reference documents --vhd; check wsl --help on your build if one is rejected. Do not unregister until you have confirmed the export finished.

Remove a distro

wsl --unregister Ubuntu-24.04

Microsoft's warning is direct: all data, settings and software in that distro are permanently lost. Then uninstall the distro's app like any Store app if it is still listed.

Uninstall WSL itself

Unregister every distro first so no Linux files are left behind. Then remove the Windows Subsystem for Linux app from Installed apps in Settings, and if you want the features gone too, clear "Windows Subsystem for Linux" and "Virtual Machine Platform" in "Turn Windows features on or off" and restart. Microsoft's pages fetched for this guide document distro removal in detail but give no single command for removing WSL itself. On managed machines, ask IT first, since policy may reinstall it.

Common errors and how to fix them

0x80370102, "a required feature is not installed". Enable Virtual Machine Platform, turn on virtualization in UEFI or BIOS, and restart. Then run bcdedit /enum | findstr -i hypervisorlaunchtype; if it shows Off, run bcdedit /set hypervisorlaunchtype Auto elevated and restart. Microsoft says other desktop hypervisors must be on versions that support Hyper-V, or turned off. Inside a VM, enable nested virtualization on the host.

WslRegisterDistribution failed with error 0x8007019e. The WSL optional component is off. Enable it in "Turn Windows features on or off" or with the first dism.exe command above, then restart.

0x80070003. WSL only runs on the system drive. Set Settings > System > Storage > Advanced storage settings > Where new content is saved back to C:. The same code can also mean virtualization is off.

Stuck at 0.0%. Microsoft suggests wsl --install --web-download -d Ubuntu.

"The term 'wsl' is not recognized". The component is not installed, or you are on Arm64 using Windows PowerShell; Microsoft says to run wsl.exe from PowerShell Core or Command Prompt.

"Windows Subsystem for Linux has no installed distributions". Launch the distro once from Start. Also check you are not signed in as Windows' built-in Administrator, a separate account that by design will not see your distros.

"WSL 2 requires an update to its kernel component". On the manual route the kernel package is missing. Install it from Microsoft's manual installation page, or move to the Store version with wsl --update.

No network on a VPN. On Windows 11 22H2 and later, Microsoft points to mirrored networking and DNS tunneling for VPN compatibility. Its troubleshooting page also documents a manual /etc/resolv.conf workaround using generateResolvConf=false, which you must revert after disconnecting.

No network on a work machine. If enterprise policy blocks local firewall rules (AllowLocalFirewallRules : False in Get-NetFirewallProfile -PolicyStore ActiveStore), WSL's own DNS rule is ignored. Microsoft's fix is an admin rule allowing UDP port 53 to the shared access service, or DNS tunneling.

0x800704ec, "blocked by group policy". Run wsl --update to get the Store version. If it still fails, your administrator has blocked WSL; ask rather than work around it.

For anything else, Microsoft's troubleshooting page explains how to collect WSL logs and file an issue on microsoft/WSL.

Common mistakes

• Downloading a "WSL installer" from an ad or download site. The only sources are the Store and github.com/microsoft/WSL.
• Installing an unofficial Store build without noticing. Read the publisher.
• Running a GitHub MSI without checking its hash, or picking a pre-release by accident.
• Making root the default user to dodge a permission error.
• Using a throwaway Linux password on an account that has sudo.
• Assuming Windows Update patches Ubuntu. Microsoft says it does not.
• Keeping projects and secrets under /mnt/c, where every Windows process and every distro can reach them.
• Binding dev servers to 0.0.0.0 or allowing all inbound traffic to make one thing work, then forgetting.
• Turning off firewall in .wslconfig to fix a VPN problem DNS tunneling or mirrored mode would have fixed.
• Leaving WSL 1 and inbox WSL enabled on managed machines, outside the Store-only policy controls.
• Running wsl --unregister before confirming a backup.

Where Safeguard fits, honestly

Safeguard does not install WSL, verify MSIs, manage Intune policy, configure Hyper-V firewall or patch Ubuntu packages. The install itself is Microsoft's and Canonical's software and process.

The connection is what comes next. WSL is where many Windows developers clone repositories, build containers and run tests, so it is where open source dependencies arrive in bulk. Safeguard scans repositories, container images and SBOM files, matches components against vulnerability data, shows which projects contain a given component and version, applies policies and gates, and can open fix pull requests when a fixed version exists. Safeguard lists its CLI and local runner for macOS, Windows and Linux; inside WSL you are on a Linux distro, so follow the Linux instructions in the CLI docs and confirm the current platform list there. Scanning the projects in your distro keeps what you build current. It does not touch the distro's own packages or the WSL kernel; apt and wsl --update still own those.

Fix it without waiting for upstream

A clean WSL install gives you a patched base. Within an hour, the projects you clone into it bring hundreds of open source dependencies, and some will carry known vulnerabilities before you write a line of code.

Whatever the vulnerability, most of the risk sits in two gaps. The first is the time between a fix being published and that fix actually running in your production builds. The second, and worse, is the time before any fix exists at all, while a maintainer works out a patch and a release schedule. Waiting through both gaps is a habit, not a requirement. Safeguard gives teams three ways to close them.

1. Autonomous remediation: pull requests, not tickets

When a fixed version exists, Safeguard's Griffin models open a tested, policy gated pull request that moves the affected dependency to the safe version. You can run it on one repository or in bulk across every project that carries the vulnerable version. Remediation covers eight categories, including dependencies, licenses, security posture and findings. Reachability analysis ranks the vulnerable code paths your application actually calls first, so the first pull requests you merge are the ones that matter most. Autonomous remediation ships switched off, with every category set to Manual, so your team decides how much runs on its own and what still needs a human approval.

2. Gold Open Source: the safe version in seconds, free

gold.safeguard.sh is free and needs no login. Search any CVE or package to see affected and fixed versions, CVSS, EPSS, CISA KEV status and a recommended safe version, or use the "Am I affected?" checker. The same data is available through a free read API, README status badges and RSS threat feeds. The safeguard-sh/gold-scan-action GitHub Action can fail a build on a known exploited vulnerability, on any known vulnerability, or never, so a version you have just removed cannot quietly come back in next week's merge.

3. Gold Registry: start from components that are already fixed

registry.safeguard.sh provides hardened, drop in replacements for upstream packages and container images. Every Gold artifact is held continuously to zero exploitable critical or high CVEs, zero malware and a completed license check, with SLSA L3 or higher provenance, a Sigstore signature and a public evidence page you can hand to an auditor. An artifact loses its Gold badge if it regresses. Teams can point their own package directory at the registry so hardened equivalents resolve without changing how developers install anything.

When upstream has no fix yet, or will not ship one, Safeguard first works to get the fix accepted upstream. If the issue is severe or upstream will not move, Safeguard builds a fork, fixes the vulnerability there and publishes a hardened Gold build, so you are not stuck on a maintainer's release schedule. You can also request a hardened, compatibility tested build of a specific package. This fork and patch flow is in early access today, so ask which packages it covers before you plan around it.

One honest limit: when the vulnerable code lives in a vendor appliance, a hosted service or an operating system runtime you do not build yourself, the fix still has to come from that vendor or distribution. The steps above apply to the open source dependencies and container images you build and ship, which is where most teams carry the largest and least tracked share of their exposure.

FAQ

How do I install WSL on Windows 11?

Open PowerShell as administrator, run wsl --install and restart. On first launch, create a Linux user name and password, then run sudo apt update && sudo apt upgrade.

How do I install WSL 2 on Windows 10?

wsl --install works on Windows 10 version 2004 (build 19041) and later; Canonical recommends at least 21H2 for Ubuntu. Older builds use Microsoft's manual steps: two dism.exe commands, the WSL 2 kernel package, then wsl --set-default-version 2.

How do I install a specific Ubuntu version on WSL?

Run wsl --list --online, then wsl --install -d Ubuntu-24.04 or another listed name. Plain Ubuntu tracks the latest LTS. Without the Store, download the .wsl image from releases.ubuntu.com, check it against SHA256SUMS, and use wsl --install --from-file.

Is WSL safe to use?

WSL is open source Microsoft software delivered through the Store, and on Windows 11 22H2 and later the Windows firewall applies to it. The risks are in how it is used: Linux processes can read your Windows files as your Windows user, your Linux account has sudo, and Windows does not patch the distro.

Can WSL access my Windows files?

Yes. Windows drives mount under /mnt, and Linux processes get the same access as the Windows user who started WSL. Windows reaches Linux files through \\wsl$. Set enabled=false under [automount] in /etc/wsl.conf to stop automatic mounting.

How do I update WSL?

Run wsl --update, then wsl --version to confirm. Update Linux packages separately inside each distro with sudo apt update && sudo apt upgrade on Ubuntu or Debian.

Does WSL 2 need Hyper-V?

It needs the Virtual Machine Platform feature, which Microsoft's FAQ describes as a subset of Hyper-V, plus the Windows Subsystem for Linux feature and hardware virtualization. Microsoft says WSL 2 works on Home editions.

How do I fix error 0x80370102 in WSL?

Enable Virtual Machine Platform, turn on virtualization in firmware, and restart. If it persists, check bcdedit /enum | findstr -i hypervisorlaunchtype and set it to Auto if it reads Off.

How do I uninstall Ubuntu from WSL?

Back up with wsl --export, then run wsl --unregister Ubuntu using the name from wsl -l -v. That permanently deletes the distro and its data.

Can my company block or restrict WSL?

Yes. Intune and group policy can disable WSL, block WSL 1 and the inbox version, and stop users changing the kernel, networking mode or firewall setting. Microsoft says it cannot yet control which distros users install or root access inside them.

See how Safeguard would help

None of these demos install WSL, check an MSI hash or configure the Hyper-V firewall. They show what happens once a developer starts working inside a fresh distro and code and dependencies arrive.

The first is a real CLI session. It installs the CLI, opens the interactive terminal with safeguard, asks it to "fix the lodash CVE in this repo", and shows it reading the finding and advisory, asking before each command, editing package.json to lodash 4.17.21, running npm install and npm test with approval, printing a summary and pushing nothing, then /permissions, /model and /scan .. In a new Ubuntu distro, the same flow brings a freshly cloned project onto fixed versions with you approving every command.

Click through it at your own pace, or open it full screen.

The second sets up the local runner on your own machine, approves it with its device code, then scans from the terminal. If your team builds inside WSL on laptops or a shared Windows build box, this is how scanning of the repositories and images there runs on hardware you control. See how the local runner and offline mode work.

Click through it at your own pace, or open it full screen.

The third connects Claude to the Safeguard MCP server with OAuth and chooses which tools Claude can use. For a team rolling WSL out across many machines, it lets someone ask in plain language which projects contain a given component and version, with only the access you grant.

Click through it at your own pace, or open it full screen.

To try the CLI yourself, download it from safeguard.sh/download and read the CLI docs. Setting up a fresh Windows machine first? Start with our Windows 11 clean install guide.

Quick check

Sources

• Microsoft Learn: How to install Linux on Windows with WSL
• Microsoft Learn: Manual installation steps for older versions of WSL
• Microsoft Learn: Basic commands for WSL
• Microsoft Learn: Set up a WSL development environment
• Microsoft Learn: What is the Windows Subsystem for Linux?
• Microsoft Learn: Comparing WSL 1 and WSL 2
• Microsoft Learn: WSL and Open Source resources
• Microsoft Learn: Accessing network applications with WSL
• Microsoft Learn: Advanced settings configuration in WSL
• Microsoft Learn: File permissions for WSL
• Microsoft Learn: Enterprise environment: set up WSL for your company
• Microsoft Learn: Intune settings for WSL
• Microsoft Learn: Configure Hyper-V firewall
• Microsoft Learn: Troubleshooting Windows Subsystem for Linux
• Microsoft Learn: Frequently asked questions about WSL
• Microsoft Learn: Get-FileHash
• Microsoft Learn: Get-AuthenticodeSignature
• Microsoft Support: Enable virtualization on Windows
• GitHub: microsoft/WSL releases
• Ubuntu on WSL documentation
• Ubuntu on WSL: Install Ubuntu on WSL 2
• Ubuntu on WSL: Distributions of Ubuntu on WSL
• Ubuntu releases: 26.04 LTS (Resolute Raccoon)
• Ubuntu tutorial: How to verify your Ubuntu download

Last reviewed: 23 October 2026. WSL ships new releases every few weeks and Microsoft updates its WSL pages often; check wsl --version and the linked pages on the day you install.