Install WSL2 and Ubuntu on Windows

The Windows Subsystem for Linux (WSL) runs a real Linux distribution inside Windows, with a full kernel, package manager and shell. WSL2, the current version, uses a lightweight virtual machine, so Docker, systemd and most Linux software behave the way they do on a Linux server. You keep Windows for everything else.

Requirements

• Windows 11, or Windows 10 version 2004 and higher (build 19041 and higher). Check with winver.
• Hardware virtualization enabled in the firmware (BIOS/UEFI). It usually is; if the install fails with a virtualization error, that is the setting to look for.
• An administrator account for the first install.

Install with one command

Open PowerShell or Windows Terminal as administrator (right-click the Start button and pick the Terminal (Admin) entry), then run:

wsl --install

This turns on the required Windows features, downloads the Linux kernel, sets WSL2 as the default and installs Ubuntu. Careful: it enables the Virtual Machine Platform feature and asks you to restart. To remove everything later, unregister the distribution with wsl --unregister Ubuntu and turn off the features again under Windows Features.

After the restart, Ubuntu opens on its own and finishes setting up. It asks for a Linux username and password. They are separate from your Windows account and the password is only used inside Ubuntu, for example with sudo.

Choose a different distribution

wsl --list --online                 # what is available
wsl --install -d Ubuntu-24.04       # a specific version
wsl --install -d Debian
wsl --list --verbose                # what is installed, and which WSL version it uses

You can keep several distributions side by side. wsl --set-default Debian picks which one opens when you type wsl with no arguments.

Check you are on WSL2

wsl --status
wsl --list --verbose
wsl --set-version Ubuntu 2            # convert a WSL1 distribution
wsl --set-default-version 2           # for future installs

In the --verbose list the VERSION column should say 2. On an up-to-date Windows it always will; the conversion commands are only needed on machines that were set up years ago.

Keep WSL up to date

wsl --update                 # update WSL itself and the kernel
wsl --version                # WSL, kernel and Windows build numbers

Inside Ubuntu, packages update the normal Linux way: sudo apt update && sudo apt upgrade.

Where the files are

• From Linux, your Windows drives are mounted under /mnt/c, /mnt/d and so on. cd /mnt/c/Users/ana/Documents works, but it is slower than the Linux file system.
• From Windows, the Linux files live at \\wsl$\Ubuntu\home\ana or \\wsl.localhost\Ubuntu\home\ana. Windows Explorer shows a Linux entry in the sidebar.
• Keep projects on the side that runs the tools. Code you build with Linux tools belongs in /home, not on /mnt/c, or git status and npm install will feel sluggish.
• Windows programs run from Linux: explorer.exe . opens the current folder, code . opens it in VS Code (with the WSL extension), notepad.exe file.txt works too.

Starting, stopping, removing

wsl                                   # open the default distribution in the current terminal
wsl -d Debian                         # a specific one
wsl --shutdown                        # stop the VM and all distributions
wsl --terminate Ubuntu                # stop one distribution
wsl --unregister Ubuntu               # delete it, including all its files

Careful: --unregister deletes the distribution’s disk immediately and there is no undo. Before you run it, copy anything you want to keep, or make a full backup with wsl --export Ubuntu C:\backups\ubuntu.tar. The matching wsl --import restores it under any name you like.

Common first problems

• WslRegisterDistribution failed with error 0x80370102: virtualization is disabled in the firmware, or Hyper-V is blocked by another hypervisor. Enable VT-x/AMD-V in BIOS.
• The command hangs or the store download fails: run wsl --install --web-download to fetch from GitHub instead of the Microsoft Store.
• Ubuntu opens but has no network: see the entry on fixing WSL2 networking and DNS.
• Old wsl.exe: on Windows 10 the one-command installer needs the April 2021 updates or newer; run Windows Update first.

Official documentation

• Install WSL
• Basic commands for WSL
• Set up a WSL development environment