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.

Once WSL2 is running, Windows Terminal is what most people actually use to interact with it day to day — worth configuring alongside this setup, not as an afterthought.

Capping resource usage with .wslconfig

WSL2's default memory allocation grows dynamically and can end up using more RAM than expected, especially with multiple distros or long-running processes. A .wslconfig file in your Windows user folder caps this explicitly:

# C:\Users\you\.wslconfig
[wsl2]
memory=8GB
processors=4
swap=2GB

This applies globally across all WSL2 distros (there's no per-distro equivalent) and takes effect after wsl --shutdown followed by relaunching a distro — editing the file alone doesn't apply it to an already-running instance.

Networking between WSL2 and Windows

WSL2 runs in a lightweight VM with its own IP address, which occasionally surprises people expecting localhost to behave exactly like a single shared machine:

# From inside WSL2, reaching a service running on Windows
curl http://$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):PORT

In practice, most day-to-day cases (a dev server running inside WSL2, accessed from a Windows browser) work transparently via localhost due to WSL2's automatic port forwarding — the manual IP lookup above is only needed for the less common reverse direction, or in networking configurations where that forwarding doesn't apply.

Backing up and moving a distro

WSL2 distros can be exported and imported as a single file, useful before a risky change or when moving to a new machine:

wsl --export Ubuntu ubuntu-backup.tar
wsl --import Ubuntu-Restored C:\WSL\Ubuntu-Restored ubuntu-backup.tar

--export captures the entire distro's filesystem as-is — installed packages, dotfiles, project directories, everything — into a single portable archive, and --import recreates it (optionally under a new name, as shown) from that archive on the same or a different machine.

Running GUI Linux apps

WSL2 supports Linux GUI applications directly (WSLg), without a separate X server setup that older WSL/X-forwarding guides describe:

sudo apt install -y gimp
gimp   # opens as a native-feeling window on the Windows desktop

This works out of the box on current Windows 11 and recent Windows 10 builds — no manual X server installation or DISPLAY variable configuration required, which was the standard (and much more fragile) workaround before WSLg existed.

Common mistakes

Related reading

• Windows Terminal: Customization Tips for Developers — shares tags: windows, productivity (same category).
• Essential Linux Commands Every Developer Should Know — shares tags: linux, productivity.
• Big O Notation Without the Math Panic — shares tags: productivity.
• Clean Code Principles That Actually Hold Up in Practice — shares tags: productivity.
• Understanding Cloud Cost Optimization Basics — shares tags: productivity.