How to Set Up WSL2 for Windows Developers

:::note[TL;DR]

Install with one command: wsl --install in PowerShell as Administrator — Ubuntu is set up automatically
Store projects inside WSL2 (~/projects/), not on /mnt/c/ — filesystem I/O is 5–10x faster
VS Code’s WSL extension (code .) runs extensions inside Linux while keeping the UI on Windows
Use Docker Desktop for Windows with the WSL2 backend — containers run natively without a separate VM
Limit memory usage in ~/.wslconfig if the Vmmem process is consuming too much RAM :::

Prerequisites

Windows 10 version 2004 (Build 19041) or later, or Windows 11
Administrator access to run PowerShell commands
Virtualization enabled in BIOS (most modern machines have this on by default)

WSL2 (Windows Subsystem for Linux 2) is a full Linux kernel running inside Windows. Not a VM you manage separately. Not a compatibility layer. An actual Linux environment where you can run apt, bash, Docker, Node, Python, git — exactly like on a Linux server.

If you’re a developer on Windows and you’re not using WSL2, you’re working harder than you need to.

Install WSL2

Open PowerShell as Administrator:

wsl --install

That’s it. By default it installs Ubuntu. Restart your machine when prompted.

First launch: Open “Ubuntu” from the Start menu. It’ll ask you to create a username and password. Use something simple — you’ll type this password often for sudo.

Verify:

wsl --version
# WSL version: 2.x.x

Install a specific distro

# List available distros
wsl --list --online

# Install a specific one
wsl --install -d Ubuntu-24.04
wsl --install -d Debian
wsl --install -d kali-linux

# Set default distro
wsl --set-default Ubuntu-24.04

Essential setup after install

# Update packages
sudo apt update && sudo apt upgrade -y

# Install common tools
sudo apt install -y curl wget git build-essential unzip

# Install zsh (optional but nice)
sudo apt install -y zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Install Node.js (via nvm)

:::warning Don’t install Node.js via apt — the version in Ubuntu’s default repos is outdated (often 2–3 major versions behind). Use nvm or a NodeSource PPA instead to get a current LTS release. :::

Don’t install Node via apt — the version is old. Use nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc

nvm install 20
nvm use 20
node -v     # v20.x.x

Install Python (via pyenv or uv)

# uv (fast, modern Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.12
uv python list

# Or install Python directly
sudo apt install -y python3 python3-pip python3-venv

Install Docker in WSL2

The best approach is Docker Desktop for Windows with WSL2 backend — it integrates automatically. Download from docker.com.

Or install Docker Engine directly in WSL2:

# Install Docker Engine
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

# Test
docker run hello-world

The scenario: You’re trying to run a project that uses Linux-only scripts, make, and Docker. On native Windows everything breaks. You spend an hour fighting path issues. With WSL2 you clone the repo, run make dev, and it just works — because WSL2 behaves like the Linux server the project was built for.

Access Windows files from WSL2

Your Windows drives are mounted at /mnt/:

ls /mnt/c/Users/YourName/Desktop
cd /mnt/c/Users/YourName/Projects

:::tip Keep all project files inside the WSL2 filesystem (~/projects/), not under /mnt/c/. File I/O across the WSL2/Windows boundary is 5–10x slower — this single change makes the biggest difference to day-to-day performance. :::

For best performance, keep your project files inside WSL2 (at ~/projects/), not on the Windows filesystem. Cross-filesystem access is slow.

Access WSL2 files from Windows

In File Explorer, type \\wsl$ in the address bar. You’ll see your distros. Bookmark \\wsl$\Ubuntu\home\yourname.

Or open the current WSL directory in Explorer:

explorer.exe .

Use VS Code with WSL2

Install the WSL extension in VS Code. Then from inside WSL2:

code .

VS Code opens with the WSL2 backend — all extensions run inside Linux, the UI runs on Windows. It feels native. Terminal in VS Code is a WSL2 terminal.

Configure WSL2 memory and CPU

By default WSL2 uses up to 50% of RAM and all CPU cores. To limit it:

Create C:\Users\YourName\.wslconfig:

[wsl2]
memory=8GB
processors=4
swap=2GB

Restart WSL2 after changing:

wsl --shutdown

Useful commands

# In PowerShell / CMD
wsl                     # open default distro
wsl --list --verbose    # list distros with status
wsl --shutdown          # stop all running distros
wsl --terminate Ubuntu  # stop a specific distro
wsl --export Ubuntu ubuntu-backup.tar    # backup
wsl --import Ubuntu C:\WSL\Ubuntu ubuntu-backup.tar  # restore
wsl --update            # update WSL kernel

# In WSL2
explorer.exe .          # open current dir in Windows Explorer
notepad.exe file.txt    # open a file in Windows Notepad
code .                  # open VS Code
clip.exe < file.txt     # copy file contents to Windows clipboard

Performance tips

Store projects in WSL2 filesystem (~/projects/), not /mnt/c/. I/O performance is 5-10x faster.
Use Windows Terminal — much better than the default WSL2 window. Install from the Microsoft Store.
Give WSL2 more RAM if you’re running Docker containers — the default 50% is often not enough for dev workloads.
Pin Windows Terminal to taskbar and set WSL2 as the default profile.

Fix common issues

“Error: 0x8007019e” on install: Enable Windows Subsystem for Linux in Windows Features (search “Turn Windows features on or off”).

Slow filesystem on /mnt/c: This is expected. Move your project files to ~/ inside WSL2.

WSL2 uses too much RAM: Set the memory limit in .wslconfig as shown above. The Vmmem process is the WSL2 VM.

Can’t connect to localhost from Windows: WSL2 has its own IP. From Windows, use localhost — WSL2 automatically forwards ports. If that fails, find the WSL2 IP with hostname -I inside WSL2 and use that.

Summary

WSL2 installs with one command (wsl --install) and gives you a full Ubuntu environment on Windows
Store your projects inside WSL2 (~/projects/) not on the Windows filesystem — I/O is 5-10x faster
VS Code’s WSL extension (code .) runs extensions inside Linux while keeping the UI on Windows
Configure memory and CPU limits in ~/.wslconfig to prevent WSL2 from consuming all your RAM
Use Windows Terminal from the Microsoft Store as your daily driver — it’s significantly better than the default WSL2 window

Frequently Asked Questions

Do I need WSL2 if I already use Git Bash or Cygwin?

WSL2 is categorically different. Git Bash and Cygwin translate Linux commands to Windows system calls — many things break or behave differently. WSL2 runs an actual Linux kernel. Docker, make, shell scripts, and most dev tools work exactly as they do on Linux servers.

Can I run GUI applications in WSL2?

Yes, since Windows 11. WSLg (built into WSL2 on Windows 11) supports running Linux GUI apps natively — they appear as regular Windows windows. On Windows 10, GUI support is limited to the terminal.

Is WSL2 suitable for production-like Docker workloads?

Yes. Docker Desktop for Windows uses WSL2 as its backend. Containers run inside the WSL2 VM, which means Linux containers work natively without the overhead of a separate VM. It’s the best Docker experience available on Windows.