A Linux terminal on Windows with WSL 2

A lot of web development tooling expects Linux. Deploy scripts, Docker, shell commands in a README: they all assume a Linux terminal. On Windows you do not need a second computer or a dual boot for that. The Windows Subsystem for Linux (WSL) runs a real Linux distribution next to Windows, and setting it up takes one command.

This guide covers WSL 2, the current version, using Microsoft's own install instructions.

What WSL 2 is

WSL 2 runs a genuine Linux kernel inside a small, managed virtual machine. You get a full Linux system: the apt package manager on Ubuntu or Debian, real file permissions, and Linux tools that behave as they would on a server. It starts in about a second and you never manage the virtual machine yourself.

The first version, WSL 1, translated Linux calls into Windows calls. Many older tutorials describe it. New installs use WSL 2 by default.

What you need

Windows 11, or Windows 10 version 2004 or later (build 19041 or later). Windows Home editions work. Hardware virtualisation must be on in your computer's firmware settings; on most recent machines it already is.

Install it

Right-click PowerShell, choose Run as administrator, and run:

wsl --install

This turns on the Windows features WSL needs and installs Ubuntu. Restart when asked. The first time Ubuntu opens, it unpacks itself and asks you for a Linux user name and password. They do not need to match your Windows account. This user can run admin commands with sudo, so pick a password you will remember.

Then bring the system up to date:

sudo apt update && sudo apt upgrade

Other distributions

Ubuntu is the default, but you can install others and run several side by side. List what is available, install one, check which WSL version each uses, and choose which one opens by default:

wsl --list --online
wsl --install -d Debian
wsl --list --verbose
wsl --set-default Debian

The easiest way to work with them is Windows Terminal, which opens each distribution in its own tab next to PowerShell.

Where to keep your files

This is the setting that matters most for speed. Microsoft recommends storing a project in the Linux file system when you work on it with Linux tools, and in the Windows file system when you use Windows tools. Working across the two is much slower, which shows up as slow npm install, git status or test runs.

Your Windows drives appear inside Linux under /mnt/c. Your Linux files appear in File Explorer under \\wsl$, and running explorer.exe . in a Linux folder opens it in Explorer.

Use VS Code with WSL

Install Visual Studio Code on Windows and add the WSL extension from Microsoft. Then, from your Linux terminal, go to a project and type code .:

mkdir -p ~/projects && cd ~/projects
git clone https://example.com/your/repo.git
cd repo
code .
explorer.exe .

VS Code opens on Windows, while the terminal, extensions, debugger and language tools run inside Linux. The first run downloads a small server component. Install Git inside your Linux distribution and configure your name and e-mail there, because that is the Git your projects will use.

Common problems and fixes

• wsl --install only prints help text. WSL is already installed. List the distributions with wsl --list --online and install one with -d.
• The install hangs at 0.0%. Download the distribution first with the --web-download option.
• An error about virtualisation. Turn on virtualisation (Intel VT-x or AMD-V) in your firmware settings, then try again.
• A distribution still runs on WSL 1. Convert it with wsl --set-version.
• Something is stuck or uses too much memory. wsl --shutdown stops every distribution; the next terminal starts fresh.
• Old behaviour or missing features. wsl --update installs the latest WSL release.

wsl --update
wsl --shutdown
wsl --install --web-download -d Ubuntu
wsl --set-version Ubuntu 2

If WSL takes more memory than you want, set limits in a .wslconfig file in your Windows user folder, then run wsl --shutdown:

# %UserProfile%\.wslconfig
[wsl2]
memory=8GB
processors=4

Microsoft's file systems guide and the troubleshooting pages linked from the install guide cover the rarer cases.

Common questions

Should I still use WSL 1?

Only if a specific tool needs it. WSL 2 is faster for Linux file work and runs real Linux software, which is why it is the default.

Does WSL work on Windows Home?

Yes. WSL 2 uses the Virtual Machine Platform feature, which Home editions include.

Can I run Docker with it?

Yes. Docker Desktop for Windows can use WSL 2 as its engine, and you can run docker commands from your Linux terminal.

How do I remove a distribution?

wsl --unregister followed by the name deletes it and all of its files. Copy anything you need out of it first.

Building on WSL and looking for paid work? Getting paid on Internetivo explains how professionals find tasks and get paid.