How to Install and Use WSL on Windows 11

The point of WSL (Windows Subsystem for Linux) is a Linux workspace you can code in next to your Windows apps, and the install itself is short: open an administrator terminal, run wsl --install, restart, and create a Linux username and password when Ubuntu first opens. The rest of this page turns that fresh install into a working setup on current versions of Windows 11: distributions, VS Code, files, memory limits, systemd and fixes by error code.

WSL, a virtual machine or dual boot?

You want	Best fit	Why
Linux command-line tools, compilers, databases or containers while you keep using Windows	WSL 2	Starts in seconds, shares files and localhost with Windows, no separate boot
A full Linux desktop, or an isolated machine you can snapshot and throw away	Virtual machine	Complete operating system with its own desktop; see set up a Linux virtual machine in Windows 11
Linux running directly on the hardware, for drivers, some gaming or full GPU control	Dual boot	Linux gets the whole PC, but only one system runs at a time; see dual booting Windows 11 and Ubuntu

WSL 2 runs a real Linux kernel in a lightweight virtual machine, so it needs hardware virtualization turned on in your PC’s UEFI/BIOS. Many PCs ship with it already on. If an error mentions virtualization, see how to enable virtualization in Windows 11 first.

Install WSL with one command

1. Search for PowerShell, right-click it and select Run as administrator (Microsoft’s documented route). Right-clicking Start and choosing Terminal (Admin) works too, if your menu shows it. Approve the User Account Control prompt.
2. Run wsl --install. According to Microsoft, this enables the WSL and Virtual Machine Platform components, installs the latest Linux kernel, sets WSL 2 as the default, and installs Ubuntu.
3. Restart the PC when asked.

Microsoft’s WSL install page lists the requirement as Windows 11 (or Windows 10 version 2004 and later) and does not limit it to particular editions. Three variations of the command are worth knowing:

• wsl --install -d Debian installs a different distribution instead of Ubuntu. Get the exact names from wsl --list --online.
• wsl --install --web-download -d Ubuntu downloads from an online source instead of the Microsoft Store. Use it when the install hangs at 0.0%.
• wsl --install --no-launch installs without opening the distribution afterward, which is handy in scripts.

If wsl --install prints only help text, WSL is already present. Run wsl --list --online and then wsl --install -d <DistroName>. Setting up a Windows 10 PC instead? The steps differ slightly there; see installing WSL2 on Windows 10.

First launch: your Linux user and first update

After the restart, Ubuntu opens and finishes unpacking. It then asks for a username and password.

• This account belongs to that one distribution and has nothing to do with your Windows sign-in. Every distribution you add, reinstall or reset asks for its own.
• Nothing appears on screen while you type the password. That is normal.
• The account is the distribution’s administrator, so this is the password sudo asks for.

Next, update the packages. Windows doesn’t update your Linux distribution for you:

sudo apt update && sudo apt upgrade

Run that every week or two. If you forget the Linux password later, open PowerShell, run wsl -u root to enter the default distribution as root, run passwd <username>, set a new password, and type exit. For a non-default distribution, use wsl -d <DistroName> -u root.

Run more than one distribution

You can keep several distributions side by side, for example Ubuntu for daily work and Debian to test a script on a second system. Each has its own files, users and installed packages.

1. See what you have: wsl -l -v lists each installed distribution, whether it is running, and whether it uses WSL 1 or WSL 2.
2. Choose which one plain wsl opens: wsl --set-default Debian.
3. Open a specific one once: wsl -d Debian, or pick it from the drop-down arrow in Windows Terminal.
4. Convert an older WSL 1 install: wsl --set-version Ubuntu 2. Microsoft warns that converting can take a while and can fail, so back up first (see the backup section below).

The Ubuntu walkthrough in installing Ubuntu with WSL on Windows 10 covers Ubuntu-specific first commands that apply here too.

Set up a development workspace

Windows Terminal

Microsoft recommends Windows Terminal for WSL, especially when you use several command lines. If it isn’t on your PC, install it from the Microsoft Store. Each distribution gets its own profile, so you can keep PowerShell and Ubuntu open in tabs or split panes.

VS Code with the WSL extension

1. Install Visual Studio Code on Windows (not inside Linux).
2. In VS Code, install the WSL extension from the Extensions view.
3. In your Linux terminal, go to a project folder and run code . (with the period). VS Code opens that folder through a remote server running inside Linux, so terminals, debuggers and extensions run on the Linux side.

Microsoft’s WSL development environment guide links follow-up tutorials for Git, Docker containers and Linux GUI apps.

Where to keep your files

Store a project in the file system of the tools that work on it. If you build and run it with Linux tools, keep it in your Linux home folder, such as ~/projects. Reaching across systems works but can be much slower.

• From Linux, your Windows C: drive is at /mnt/c.
• From Windows, Linux files are at \\wsl$\<DistroName>\home\<UserName> in File Explorer.
• Run explorer.exe . in Linux to open the current Linux folder in File Explorer.

A typical setup: a developer clones a web app into ~/projects/shop, opens it with code ., runs the dev server in Linux, and views it in Edge on Windows at localhost. Nothing lives on /mnt/c, so builds stay fast.

The same pattern works for local services: running Redis under WSL installs it in Ubuntu and reaches it from Windows at localhost.

Tune memory, processors and systemd

WSL has two settings files, both described in Microsoft’s WSL configuration reference.

.wslconfig: limits for the whole WSL 2 VM

This file doesn’t exist until you create it at %UserProfile%\.wslconfig (for example C:\Users\<name>\.wslconfig). Settings go under a [wsl2] heading. By default WSL 2 can use 50% of your PC’s memory, all of its logical processors, and a swap file sized at 25% of memory. On a 16 GB laptop that runs a browser and an editor alongside WSL, capping memory helps:

[wsl2]
memory=6GB
processors=4

wsl.conf: settings for one distribution

Inside the distribution, /etc/wsl.conf holds per-distribution options. systemd, which many Linux services expect, is already on in the current Ubuntu that wsl --install sets up, according to Microsoft’s systemd guide (WSL 0.67.6 or later). Run systemctl status to check. For a distribution where it’s off (the setting defaults to off in Microsoft’s reference), edit the file with sudo nano /etc/wsl.conf and add:

[boot]
systemd=true

After the restart below, systemctl status should show a running system.

Apply changes

Run wsl --shutdown in PowerShell, wait about 8 seconds, and open the distribution again. wsl --list --running confirms nothing is still running. For other ways to restart, see how to restart WSL on Windows 11.

Commands worth keeping handy

Command (PowerShell)	What it does
wsl --version	Shows the WSL, kernel and related component versions
wsl --status	Shows the default distribution and default WSL version
wsl --update	Updates WSL itself (add --web-download to download from GitHub instead of the Store)
wsl --shutdown	Immediately stops every distribution and the WSL 2 VM
wsl --terminate Ubuntu	Stops one distribution only
wsl --user <name>	Opens the default distribution as a specific user
wsl --list --running	Lists distributions that are running right now

Inside Linux, add .exe to run the same commands, for example wsl.exe --status.

Back up, move or reset a distribution

• Back up: wsl --export Ubuntu D:\Backups\ubuntu.tar saves the whole distribution to one file.
• Restore or move to another drive: wsl --import Ubuntu-2 D:\WSL\Ubuntu-2 D:\Backups\ubuntu.tar creates a distribution from that file in the folder you name. To put a brand-new distribution elsewhere from the start, add --location to wsl --install.
• Imported distributions and your user: an imported copy has no launcher, so ubuntu config --default-user doesn’t work for it. Use wsl -d Ubuntu-2 --user <name>, or set the default user in /etc/wsl.conf.
• Reset: wsl --unregister Ubuntu deletes the distribution. Microsoft is explicit that all of its data, settings and software are permanently lost, so export first. Running wsl --install -d Ubuntu afterward gives you a clean copy.

Fix WSL by error code

These causes and fixes follow Microsoft’s WSL troubleshooting page.

Error	What it means	Fix
0x80370102	The virtual machine can’t start: virtualization is off in firmware, Virtual Machine Platform isn’t enabled, or the hypervisor is set not to launch	Turn on virtualization in UEFI/BIOS, enable Virtual Machine Platform, restart. In an admin PowerShell, bcdedit /enum | findstr -i hypervisorlaunchtype; if it says Off, run bcdedit /set hypervisorlaunchtype Auto
0x8007019e	The Windows Subsystem for Linux optional component isn’t enabled	Turn it on in Turn Windows features on or off, then restart
0x80070003	The distribution is stored on a drive other than the system drive	Settings > System > Storage > Advanced storage settings > Where new content is saved, set new apps to C:, then reinstall
0x8000FFFF	An unexpected failure with no single cause	Run the terminal as administrator, then wsl --update, wsl --shutdown, sfc /scannow and DISM /Online /Cleanup-Image /RestoreHealth
0x80040306	The legacy console is turned on	In Command Prompt, right-click the title bar, choose Properties, clear Use legacy console
0x80040154	A Windows update turned the WSL feature off	Turn Windows Subsystem for Linux back on in Windows features

Microsoft also notes that very old processors without SLAT (second-level address translation) can’t run WSL 2 at all.

When Linux has no internet

VPNs are the usual cause. Many VPNs apply DNS rules that only reach WSL when DNS tunneling is on. Microsoft’s reference lists dnsTunneling as on by default under [wsl2] in .wslconfig, so check that the file doesn’t set dnsTunneling=false and that /etc/wsl.conf doesn’t turn off generateResolvConf.

If that isn’t enough, try mirrored networking, which Microsoft’s WSL networking page describes as mirroring your Windows network interfaces into Linux: add networkingMode=mirrored under [wsl2], then wsl --shutdown. Microsoft lists a few VPN clients as incompatible with mirrored mode and, for its Global Secure Access client, recommends the opposite (turn DNS tunneling off or switch back to networkingMode=nat). Check your VPN’s own WSL guidance if problems continue.

WSL setup questions

Can I install WSL without the Microsoft Store?

Yes. wsl --install --web-download -d Ubuntu downloads the distribution from an online source instead of the Store, and wsl --update --web-download updates WSL itself from GitHub. That helps on PCs where the Store is blocked by policy. The opposite case also exists: wsl --install --inbox installs WSL as the built-in Windows component, so it updates through Windows Update instead of the Store.

Can Linux apps with a window run on Windows 11?

Yes. WSL can run Linux GUI apps, which open in their own windows on the Windows desktop. Microsoft’s Linux GUI apps tutorial covers the setup and lists what your PC needs.

Should a distribution ever go back to WSL 1?

Rarely. WSL 2 is the default because it uses a real Linux kernel and runs Linux tools faster in the Linux file system. If a project must live on /mnt/c and be worked on mainly with Linux tools, testing that one distribution on WSL 1 with wsl --set-version <Distro> 1 is an option. Back it up first.

With WSL installed, a sensible next step is to clone a project into your Linux home folder, open it with code ., and set a .wslconfig memory cap if your PC has 16 GB or less.