WSL2 Setup Guide: Running Linux on Windows for Development

WSL2 gives you a real Linux kernel running alongside Windows, close enough to native performance that most Windows developers doing web/backend work use it as their default environment instead of dual-booting or running a full VM.

Install WSL2

Open PowerShell as Administrator:

wsl --install

This installs WSL2, sets it as the default version, and installs Ubuntu by default. A restart is required afterward.

To install a specific distro instead:

wsl --install -d Debian
wsl --list --online   # see all available distros

First-time setup

After the restart, the installed distro launches automatically and prompts for a Unix username and password — this is separate from your Windows login.

sudo apt update && sudo apt upgrade -y

Where your files actually live

This is the detail that trips people up most: WSL2 has its own Linux filesystem, separate from your Windows C: drive.

• Your Linux home directory (~, i.e. /home/username) is the fast, native Linux filesystem — this is where your code should live for real development work.
• Windows drives are accessible from WSL at /mnt/c/, /mnt/d/, etc. — but file operations across this boundary are noticeably slower, since every access crosses the Windows/Linux filesystem bridge.

# Slow — working across the Windows/Linux boundary
cd /mnt/c/Users/you/projects/my-app
 
# Fast — working entirely inside the Linux filesystem
cd ~/projects/my-app

Clone your repos into ~/projects inside WSL, not into a Windows-side folder you access via /mnt/c/ — this single decision is the biggest performance factor in WSL2 setups.

VS Code integration

Install the WSL extension in VS Code. From inside your WSL terminal:

cd ~/projects/my-app
code .

This opens VS Code running on Windows, but connected to a server process running inside WSL — extensions, the terminal, and language servers all run in the Linux environment, while you get the native Windows UI. It's the detail that makes WSL2 feel seamless rather than like switching between two separate machines.

Common setup after install

# Node via nvm (avoid installing node directly via apt — it's often outdated)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts
 
# Git config (or better, share Windows' credential manager — see below)
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Sharing Git credentials with Windows

Rather than setting up SSH keys separately inside WSL, you can use Windows' Git Credential Manager from within WSL:

git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

This lets WSL's git push/git pull reuse the same authenticated sessions as Git on Windows, avoiding duplicate credential setup.

When WSL2 isn't the right tool

Native Windows development (via Visual Studio, .NET, or Windows-specific APIs) doesn't benefit from WSL2 — you'd be adding a translation layer for no reason. WSL2 earns its place specifically when your target deployment environment is Linux (which describes most web and backend development) and you want your local dev environment to match it closely.