How to Install WSL2 on Windows 11

Installing the Windows Subsystem for Linux used to be a chore — enable two features, download a kernel package, set a default version, then go find a distribution. On Windows 11, almost all of that collapses into one command. Run it, reboot, set a username, and you have a real Linux environment running next to Windows.

This guide covers the fast path first, since it’s what most people need. Then it gets into the parts that actually trip people up: choosing a distribution, confirming you’re on WSL2 and not WSL1, and clearing the virtualization and “it just printed the help text” errors that send people in circles.

What WSL2 gives you#

WSL2 runs a genuine Linux kernel inside a lightweight virtual machine that Windows manages for you. That’s the key difference from the original WSL1, which translated Linux system calls instead of running a real kernel. WSL2 gives you full system-call compatibility and much better file-system performance for Linux workloads, which is why it’s the default and the version you want for most development work.

It does have trade-offs. Because it’s VM-based, WSL2 needs the Virtual Machine Platform feature and hardware virtualization turned on. Crossing the Windows/Linux file-system boundary (working on files stored under /mnt/c) is slower than staying inside the Linux file system. For nearly everyone, WSL2 is still the right default.

The one-command install#

Open PowerShell or Windows Terminal as administrator (right-click Start → Terminal (Admin)). Then run:

wsl --install

That single command does the whole setup: it enables the Windows Subsystem for Linux and Virtual Machine Platform features, downloads and installs the Linux kernel, sets WSL2 as the default version, and installs Ubuntu as the default distribution.

When it finishes, restart your PC. After the reboot, the Linux distribution launches and asks you to create a UNIX username and password. This account is separate from your Windows sign-in — it’s the Linux user, so pick credentials you’ll remember for sudo.

Enter new UNIX username: yourname
New password:
Retype new password:

That’s it. You now have WSL2 running. To open it later, type wsl in a terminal, or launch the distribution from the Start menu.

Confirm you’re actually on WSL2#

A clean install on Windows 11 puts you on WSL2, but it’s worth verifying — especially if you upgraded from an older setup that may have left a distribution on WSL1.

wsl -l -v

The output lists each distribution with a VERSION column:

  NAME      STATE           VERSION
* Ubuntu    Running         2

If a distribution shows 1, convert it:

wsl --set-version Ubuntu 2

And make sure any future installs default to version 2:

wsl --set-default-version 2

Keep WSL updated#

The WSL kernel and the WSL app itself update separately from your Linux distribution’s packages. Keeping them current clears a lot of networking and startup bugs that older builds had.

wsl --update
wsl --version

Run wsl --update after the initial install and occasionally afterward. Inside the Linux distribution, you still update packages the normal way for that distro — for example, on Ubuntu:

sudo apt update && sudo apt upgrade -y

Keep the two separate in your head: wsl --update maintains the Windows-side WSL plumbing, while apt/dnf/zypper maintain the software inside your Linux install. Updating one does nothing for the other, which is a common point of confusion when something works in the distro but the WSL platform itself is out of date.

Fixing the common install problems#

Most failures fall into a few buckets. Here’s how to tell them apart and clear them.

”wsl —install just shows the help text”#

This means the command ran but didn’t get what it expected — often because WSL is already present, or no usable distribution argument was passed. List what’s available and install one explicitly:

wsl --list --online
wsl --install -d Ubuntu

Confirm you opened the terminal as administrator. A non-elevated prompt can’t enable the required Windows features.

Virtualization isn’t enabled#

WSL2’s VM needs hardware virtualization. If WSL2 distributions won’t start, check that virtualization is on. In Task Manager → Performance → CPU, “Virtualization” should read Enabled. If it’s disabled, turn it on in your firmware — the setting is usually named Intel VT-x, AMD-V, or SVM Mode in BIOS/UEFI.

The wsl --install command turns on the Virtual Machine Platform Windows feature, but it can’t change a firmware switch for you. If you also run VirtualBox or VMware on the same machine, be aware that Windows virtualization features can conflict with them — the same class of issue covered in our notes on Hyper-V vs. other hypervisors applies to the platform WSL2 relies on.

Older Windows builds: the manual path#

If you’re on a build too old for the one-command install, enable the features by hand from an elevated PowerShell, then reboot:

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

After the restart, set WSL2 as the default and install a distribution. Microsoft’s manual-install documentation lists the kernel-package step needed on those older builds. The single command is the better route whenever your Windows version supports it.

A few habits that keep WSL happy#

Store your active project files inside the Linux file system (your Linux home directory) rather than under /mnt/c, where cross-boundary access is slower. Use wsl --shutdown to fully stop the WSL VM when you want a clean restart of the environment — it’s cleaner than closing a terminal window. And run wsl --update periodically so you’re not chasing bugs that were already fixed upstream.

You can also run more than one distribution side by side. Install several with wsl --install -d, list them with wsl -l -v, and set whichever you prefer as the default with wsl --set-default <Name>. Each distribution keeps its own packages and home directory, which is useful when one project needs Ubuntu and another targets a different distro.

If something on the Windows side seems broken after enabling features — networking acting strange, for instance — the underlying cause is sometimes a Windows update or feature conflict rather than WSL itself. Our guide on fixing Wi-Fi connected but no internet covers the network-reset basics that occasionally come up after enabling Virtual Machine Platform.

Wrapping up#

On Windows 11, installing WSL2 is genuinely one command followed by a reboot and a username. wsl --install handles the features, the kernel, the default version, and a starter distribution. Verify you landed on version 2 with wsl -l -v, pick a different distro with -d if Ubuntu isn’t your choice, and keep the platform current with wsl --update.

The only steps that need attention are the environment ones: hardware virtualization in firmware, the Virtual Machine Platform feature, and the awareness that WSL2 shares that platform with other hypervisors. Sort those out and WSL2 runs quietly in the background as a full Linux environment alongside Windows.