WSL: install Linux inside Windows

Why this matters

The browser terminal on the site is good for the first steps, but it's limited. You can't install an arbitrary package, you can't leave files until tomorrow, you can't run Docker. A local environment removes these limits.

WSL (Windows Subsystem for Linux) gives you a real Linux next to Windows. It's not an emulator and not a set of utilities like Cygwin. In the second version a full Linux kernel runs inside, and the distro installs from a catalog with one command.

You don't need a second computer, you don't need to partition a disk, Windows stays as it is.

What you need before starting

Windows 10 version 2004 (build 19041) or newer, or Windows 11. Check the version: Win+R, type winver. On older builds the command wsl --install isn't available: update Windows through Windows Update first.

You need hardware virtualization enabled. Open Task Manager, the "Performance" tab, the "CPU" section. There's a line "Virtualization". If it says "Disabled", enable it in your motherboard's UEFI (BIOS); the setting is named differently depending on the vendor: Intel VT-x, AMD-V, SVM Mode.

Installation

Open PowerShell as administrator: right-click the Start button, choose "Terminal (Admin)" or "Windows PowerShell (Admin)". Then one command:

wsl --install

It enables the Windows components "Windows Subsystem for Linux" and "Virtual Machine Platform", downloads the Linux kernel, makes WSL2 the default version, and installs the Ubuntu distro. Then restart your computer. This step is required.

Need a different distro? First check the catalog, then install by name:

wsl --list --online

wsl --install -d Debian

Short form of the first command: wsl -l -o. If you don't know what to pick, go with Ubuntu: it has the most documentation and answered questions.

wsl --install without parameters only works while WSL isn't installed at all. If it prints the help for wsl instead of installing, WSL is already enabled. Then install the distro explicitly: wsl --install -d Ubuntu.

First launch

After restarting, find the app named after the distro in the Start menu and run it. The first start takes a couple of minutes: the system unpacks the image. Later launches are fast.

Next the distro will ask you to come up with a username and a password. This is a separate account inside Linux. It has nothing to do with your Windows account. Type the name in Latin letters, lowercase, no spaces. This user becomes the default user and is allowed to run commands with sudo, that is, as an administrator.

The password doesn't show while you type it, not even as asterisks. That's normal: that's how password input works on Unix. Type it blind and hit Enter.

You'll need the password for every sudo, so write it down. If you forget it anyway, you can reset it from Windows. In PowerShell, enter the distro as root:

wsl -u root

Inside, set a new password for your user (use your own name instead of anna) and exit:

passwd anna

exit

Changing a password you remember is simpler: plain passwd as your own user.

Update packages

The distro image is prebuilt, some packages in it are already outdated, and Windows itself doesn't update Linux packages. First thing, update the list and the packages themselves:

sudo apt update

sudo apt upgrade

apt update downloads a fresh list of what's available. apt upgrade updates what's installed. The order matters: without the first command, the second won't know that new versions came out. People often write them on one line: sudo apt update && sudo apt upgrade.

Check that it all worked

Three commands inside Linux:

uname -r

6.6.87.2-microsoft-standard-WSL2

uname -r prints the kernel version. The numbers depend on updates, and the microsoft-standard-WSL2 ending means it's Microsoft's WSL2 kernel.

cat /etc/os-release

This shows which distro you have and its version (the PRETTY_NAME line).

pwd

/home/anna

pwd shows the current directory. Right after launch this is your Linux home directory /home/<name>.

Windows drives are also visible inside WSL: C: lives at /mnt/c. It's better to work on projects in your Linux home directory, not in /mnt/c: it's faster. More on this in the next lesson.

WSL1 and WSL2

There are two versions, and they work differently.

WSL1 translated Linux system calls into Windows calls on the fly. There was no real kernel there, so some programs didn't work.

WSL2 runs a real Linux kernel in a lightweight virtual machine managed by Windows itself. System calls are fully supported, Docker works. WSL2 is installed by default now, and there's no need to change that.

You can check the installed distro's version from PowerShell:

wsl --list --verbose

  NAME      STATE           VERSION
* Ubuntu    Running         2

The VERSION column should show 2. If it shows 1, switch it (take the distro name from the NAME column):

wsl --set-version Ubuntu 2

Switching can take a while. If the distro already has important files, make a backup first.

If something went wrong

wsl --install isn't recognized or doesn't install anything. Check the build with winver: you need 19041 or higher. If the build is fine but the command prints the help text, WSL is already enabled: install the distro with wsl --install -d Ubuntu.

Error 0x80370102 or a message about Virtual Machine Platform. Virtualization is disabled in UEFI. Go back to "What you need before starting". If Windows itself runs inside a virtual machine, you need nested virtualization.

Installation stuck at 0.0%. Download the distro directly, bypassing the Microsoft Store:

wsl --install --web-download -d Ubuntu

The distro launches and closes right away, or behaves strangely. Shut down the whole subsystem and open a terminal again:

wsl --shutdown

wsl --shutdown immediately stops all distros and the WSL2 virtual machine. The next terminal launch brings everything back up. You don't need to restart Windows for this.

Common mistakes

• Typing the PowerShell command (wsl ...) inside Ubuntu, or sudo apt ... in PowerShell. Look at the prompt: PS C:\...> is PowerShell, anna@DESKTOP-ABC123:~$ is Linux.
• PowerShell opened without administrator rights, so wsl --install can't enable the Windows components.
• Skipping the restart after wsl --install.
• Closing the first-launch window before creating a user, so the distro opens as root. Working as root all the time isn't a good idea: one mistake in a command and the whole system is affected.
• The password "doesn't appear", so people retype it many times. The characters simply aren't displayed.

What you'll need for the task

In the lab labs/01-install-wsl you'll install WSL2 on your own computer and check the result with a script. You'll need:

• wsl --install and wsl --install -d <name> in PowerShell as administrator;
• wsl --list --verbose and wsl --set-version <name> 2;
• sudo apt update and sudo apt upgrade inside Linux;
• uname -r, id, pwd for self-checks;
• wsl in PowerShell to open Linux right in the current Windows folder.

The lab only works on Windows. On macOS and Linux the lesson is reference material.