WSL2 — Linux on top of Windows
WSL2 — Linux on top of Windows
Developing on Windows often runs into "Linux-only tools" — Docker, certain CLIs, shell scripts, compilation environments. WSL2 raises a real Linux environment inside the same machine without dual-booting or a heavyweight VM.
1. About WSL
WSL stands for Windows Subsystem for Linux. The first version landed in the Windows 10 Anniversary Update (1607) in 2016, and WSL2 became official in the Windows 10 2004 update of May 2020. From 2022 it ships as a standalone app from the Microsoft Store via wsl --install.
| Generation | Behavior | Released |
|---|---|---|
| WSL1 | A compatibility layer that translates Linux syscalls into Windows API. | 2016 |
| WSL2 | Runs a real Linux kernel as a lightweight Hyper-V VM. | 2020 |
WSL2 is overwhelmingly more compatible and the recommended default.
2. Install
On Windows 10 2004+ or Windows 11, one line in an admin PowerShell:
wsl --install
This handles the following at once:
- Enable the WSL feature.
- Enable Virtual Machine Platform.
- Install the latest Linux kernel.
- Set WSL2 as the default version.
- Install the Ubuntu distribution.
Reboot once after installation. Use the Start menu's "Ubuntu" entry or the wsl command to enter the shell.
wsl --list --online # available distros
wsl --install -d Debian # install another distro
wsl --list --verbose # installed list and versions
wsl --set-default Ubuntu # set default distro
wsl --shutdown # stop all WSL instances
wsl --terminate Ubuntu # stop a specific distro
wsl --unregister Ubuntu # full removal (data lost)
3. WSL1 vs WSL2
| Item | WSL1 | WSL2 |
|---|---|---|
| Architecture | Linux syscalls → Windows translation | Real Linux kernel (Hyper-V VM) |
| Syscall coverage | Partial | Full |
| Startup speed | Instant | 1-2 seconds |
| Memory | Shared | Virtual memory pool (dynamic allocation) |
| Linux-side file I/O | Slow | Fast (ext4) |
Windows-side file I/O (/mnt/c) |
Fast | Slow (9P protocol) |
| Docker | Not supported | Supported (Docker Desktop) |
| systemd | Not supported | Supported (since 2022) |
| GPU | Not supported | CUDA, DirectX supported |
wsl --set-version Ubuntu 2
wsl --set-default-version 2
4. File system — where to keep code
| Location | What's faster | Recommendation |
|---|---|---|
\\wsl$\Ubuntu\home\user\project (Linux side) |
Linux tools | When using Linux tools primarily. |
C:\Users\name\project (/mnt/c/...) |
Windows tools | When using Windows tools primarily. |
I/O across the boundary is the slowest path. Tasks that create tens of thousands of small files, like Node's npm install or git operations, take a noticeable hit when both sides mix.
Recommendation — keep code intended for Linux tools inside WSL (~/), code intended only for Windows tools on C:\. When a single project uses both, keep it inside WSL and reach it from Windows through VS Code.
5. VS Code integration
The Remote - WSL extension is the standard. From a WSL shell:
cd ~/project
code .
VS Code automatically launches a server on the WSL side and the Windows-side UI attaches to it. Extensions, terminals, and debuggers all run on the Linux side, so paths, line endings, and the executable bit feel natural. The bottom-left corner shows WSL: Ubuntu.
6. Docker Desktop on WSL2
Docker Desktop's WSL2 backend is the de facto standard. Enabling WSL2 integration during Docker Desktop install lets the docker command work directly inside a WSL shell.
Pros:
- Faster startup without a heavy Hyper-V VM.
- Other distros inside WSL share the same Docker.
- More efficient resource usage than the Windows-side Hyper-V mode.
Memory and CPU limits via .wslconfig:
# C:\Users\<user>\.wslconfig
[wsl2]
memory=8GB
processors=4
swap=4GB
7. Enabling systemd
Since 2022, WSL2 officially supports systemd. Some packages (Snap, certain service daemons) require it. Turn it on through /etc/wsl.conf:
[boot]
systemd=true
Save, then run wsl --shutdown once from PowerShell. systemd activates on the next launch.
8. Other options
- Hyper-V VM — the traditional virtual machine. Heavy but strongly isolated.
- VirtualBox — Oracle's VM. Works on other host OSes too.
- VMware Workstation — commercial VM.
- Multipass — Canonical's Ubuntu VM tool.
- Cygwin · MSYS2 · Git Bash — GNU-tool simulations on top of Windows. Not real Linux.
- Dual boot — fastest, but the workflow split costs a lot.
WSL2 is built by Microsoft itself, so the integration is tight and friction with Windows day-to-day tasks stays low.
9. Common commands
# Inside WSL (assuming Ubuntu)
sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl build-essential
# Access Windows-side files
ls /mnt/c/Users/<name>/Documents
# Send to Windows clipboard
echo "hello" | clip.exe
# Run Windows commands
cmd.exe /c "echo Hello from cmd"
powershell.exe -c "Get-ChildItem"
# Open a browser
explorer.exe https://example.com
# WSL-side IP
hostname -I
# From the Windows side
wsl ls -la /home/user
wsl --user user -d Ubuntu bash -c "cd /home/user/project && pnpm install"
copy file.txt \\wsl$\Ubuntu\home\user\
10. Common pitfalls
I/O across the two sides — the biggest trap. Keep large directories on the WSL side.
Line endings — when git's core.autocrlf is on, checkouts inside WSL can mix in CRLF. The safer choice is * text=auto eol=lf in .gitattributes.
Executable bit — a .sh placed on the Windows side shows up without execute permission. When chmod +x does not stick, set it explicitly with git update-index --chmod=+x.
localhost ports — a server inside WSL2 is normally reachable from Windows at localhost:port (auto-forwarded). When that fails, find the IP with wsl hostname -I.
DNS — sometimes corporate networks scramble DNS. /etc/resolv.conf is auto-generated; turn it off with [network] generateResolvConf=false in /etc/wsl.conf and write it manually.
RAM that looks like a memory leak — WSL2's vmmem process holds onto cache. Either set the memory limit in .wslconfig or run wsl --shutdown.
VHDX disk not reclaimed — docker_data.vhdx does not auto-shrink with prune (MS WSL #4699). Reclaim it with Optimize-VHD -Mode Full.
GUI apps — WSLg (Windows 11 and Win10 2004+ patch) provides GUI directly without an X server. Before that, an X server like VcXsrv or X410 had to be installed separately.
Closing thoughts
WSL2 brings a real Linux environment to Windows users in the most natural way available. Keeping an eye on cross-side I/O (WSL ↔ NTFS) is enough to avoid most daily-use friction. VHDX disk reclaim is the one operational chore worth scheduling.
Next
- (end of environment)
Microsoft WSL · WSL GitHub · WSL Release Notes · .wslconfig · Docker Desktop WSL2 · WSLg · WSL1 vs WSL2 for reference.