A WSL2 setup that stays fast after the first week.

01 · THE DECISION

WSL2 is a real Linux kernel in a lightweight VM.

WSL1 translated Linux system calls into Windows ones. WSL2 runs an actual Linux kernel in a managed virtual machine, which is why compatibility is excellent and why the filesystem boundary matters so much.

02 · INSTALLATION

One command, then confirm you got version 2.

# Enables the features and installs the default distribution
wsl --install

# Or pick one explicitly
wsl --list --online
wsl --install -d Ubuntu-24.04

# After the reboot, confirm the version column says 2
wsl -l -v

# Keep the subsystem itself updated
wsl --update

Choosing a distribution

• Ubuntu LTS — the default for a reason. The largest share of documentation and CI images assume it, so error messages match search results.
• Debian — leaner, slower moving. Good when your servers run Debian.
• Fedora or openSUSE — newer toolchains, more churn. Fine if you already know the ecosystem.
• Alpine — tempting for size, awkward for development because of the musl C library. Use it in containers, not as your workstation shell.

You can install several side by side and switch with wsl -d name. A per-project distribution is a legitimate way to keep two incompatible toolchains apart, and each one is a file you can export and re-import.

# Export a distribution to a single archive
wsl --export Ubuntu-24.04 D:\wsl\ubuntu-backup.tar

# Re-import it, under any name, on any machine
wsl --import work-ubuntu D:\wsl\work D:\wsl\ubuntu-backup.tar

03 · THE CONFIG FILE

Create .wslconfig before WSL eats your memory.

By default WSL2 will claim a large share of system RAM and is slow to give it back. On a 16 GB machine, that is the difference between a usable desktop and one that swaps whenever a build starts.

Create .wslconfig in your Windows user profile — C:\Users\yourname\.wslconfig — and restart the subsystem with wsl --shutdown.

[wsl2]
# Roughly half of physical RAM is a sane starting point
memory=8GB
processors=4
swap=4GB

# Reclaim unused memory back to Windows instead of holding it
autoMemoryReclaim=gradual

# Sparse VHD keeps the virtual disk from growing forever
sparseVhd=true

# Mirrored networking makes localhost work in both directions
networkingMode=mirrored
dnsTunneling=true
autoProxy=true

[experimental]
hostAddressLoopback=true

Choosing the numbers

• Memory — about half of physical RAM. Raise it if builds are being killed, lower it if Windows starts paging.
• Processors — leave at least two cores for Windows. All of them is not faster once the host starts contending.
• Swap — worth having. Without it, an out-of-memory situation kills the process instead of slowing down.
• Networking — mirrored mode makes services reachable on localhost from both sides, which removes the most common WSL networking confusion. If a VPN or corporate network client misbehaves, remove that line first.

04 · THE ONE BIG MISTAKE

Keep your code on the Linux side. All of it.

This is the single most common WSL2 performance complaint, and it has one cause: working on files that live on the Windows drive, accessed through /mnt/c.

Crossing the filesystem boundary goes through a network protocol. For a compiler or a package manager touching thousands of small files, the overhead is severe — installs and builds that should take seconds take minutes, and file watchers become unreliable.

mkdir -p ~/projects
cd ~/projects
git clone git@github.com:you/your-project.git
cd your-project

# Open it in VS Code on Windows, running the server inside WSL
code .

You can still reach these files from Windows through \\wsl$\Ubuntu-24.04\home\you\projects — good for dropping a file into Explorer, wrong for running a Windows build tool against the whole tree.

05 · WIRING IT UP

Editor, Git, containers, keys and the GPU.

VS Code

Install the WSL extension on Windows and run code . from inside the Linux shell. The editor UI stays on Windows while the language servers, terminal, debugger and extensions run in Linux — which means the extensions see the same toolchain your build does. Trying to open a project through \\wsl$ instead is the setup that produces mysteriously broken IntelliSense.

Git

• Install and configure Git inside WSL, and use it for anything in the Linux filesystem.
• Set git config --global core.autocrlf input in Linux so you do not commit Windows line endings.
• Sharing a credential helper with Windows works, but a plain SSH key inside WSL is simpler and has fewer failure modes.

Docker

Docker Desktop uses WSL2 as its backend and exposes the docker command inside your distributions. If you would rather not run Docker Desktop, you can install the Docker engine directly inside a WSL distribution — the container alternatives guide covers when that is worth the extra setup.

SSH keys

ssh-keygen -t ed25519 -C "you@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub   # add this to GitHub

Keep the Linux key separate from your Windows key rather than sharing one across the boundary. Two keys on one account is normal, and it means revoking one does not lock you out of both environments.

GPU compute

CUDA workloads run in WSL2 with the Windows driver providing the GPU — you install the CUDA toolkit inside Linux, but not a Linux display driver. Installing one is the classic mistake and breaks the passthrough. This is what makes WSL2 a reasonable place to run local models; see the local LLM guide for the hardware side.

06 · WHEN IT MISBEHAVES

The six failures you will actually hit.

# Stop everything (this is the fix for a surprising number of issues)
wsl --shutdown

# Update the subsystem itself
wsl --update

# Check state and versions
wsl -l -v

# Last resort for one distribution: export, unregister, re-import
wsl --export Ubuntu-24.04 D:\wsl\backup.tar
wsl --unregister Ubuntu-24.04

Export before you unregister. Unregistering deletes the distribution and everything in it, without a confirmation worth the name.

07 · QUICK ANSWERS

WSL2, briefly.