Set Up WSL Development Environment

Configure a complete WSL2 development environment for cross-platform work.

When to Use

Setting up a new Windows machine for development
Configuring WSL2 for the first time
Adding development tools to an existing WSL installation
Setting up cross-platform workflows (WSL + Windows tools)

Inputs

Required: Windows 10/11 with WSL2 support
Optional: Preferred Linux distribution (default: Ubuntu)
Optional: Languages to set up (Node.js, Python, R)
Optional: Additional tools (Docker, tmux, fzf)

Procedure

Step 1: Install WSL2

In PowerShell (Administrator):

wsl --install
wsl --set-default-version 2

Restart if prompted. Ubuntu installs by default.

Expected: After reboot, wsl --list --verbose shows the distribution running under WSL version 2. The wsl command opens a Linux shell.

On failure: If WSL2 installation fails, enable the "Virtual Machine Platform" and "Windows Subsystem for Linux" Windows features manually via optionalfeatures.exe. On older Windows 10 builds, a kernel update may be required from Microsoft.

Step 2: Configure WSL Resource Limits

Create ~/.wslconfig in Windows home directory:

[wsl2]
memory=8GB
processors=4
localhostForwarding=true

Expected: The .wslconfig file exists in the Windows user home directory (e.g., C:\Users\Name\.wslconfig). After running wsl --shutdown and restarting WSL, resource limits are applied.

On failure: If the config has no effect, verify the file is in the correct location (Windows home, not WSL home). Run wsl --shutdown and reopen WSL for changes to take effect.

Step 3: Update and Install Essentials

sudo apt update && sudo apt upgrade -y
sudo apt install -y \
  build-essential \
  curl \
  wget \
  git \
  git-lfs \
  vim \
  htop \
  tree \
  jq \
  ripgrep \
  fd-find \
  unzip \
  zip

Create useful aliases:

echo 'alias fd="fdfind"' >> ~/.bashrc

Expected: All packages install without errors. Commands like git --version, jq --version, rg --version, and tree execute successfully.

On failure: If apt install fails, run sudo apt update first to refresh package lists. For packages not found, check that the Ubuntu version supports them or install from alternative sources (e.g., snap, cargo, or manual download).

Step 4: Configure Git

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
git config --global init.defaultBranch main
git config --global core.autocrlf input
git config --global color.ui auto
git config --global core.editor vim

Expected: git config --list shows the correct user name, email, default branch (main), autocrlf (input), and editor settings.

On failure: If settings are not applied, verify you used --global (not --local which only applies to the current repo). Check that ~/.gitconfig contains the expected entries.

Step 5: Set Up SSH Keys

ssh-keygen -t ed25519 -C "your.email@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub
# Add to GitHub: Settings > SSH and GPG keys

Test: ssh -T git@github.com

Expected: ssh -T git@github.com returns "Hi username! You've successfully authenticated." The SSH key pair exists at ~/.ssh/id_ed25519 and ~/.ssh/id_ed25519.pub.

On failure: If authentication fails, verify the public key was added to GitHub (Settings > SSH and GPG keys). Check that ssh-agent is running and the key is loaded with ssh-add -l. If the agent is not running, add eval "$(ssh-agent -s)" to ~/.bashrc.

Step 6: Install Node.js (via nvm)

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

Expected: node --version and npm --version return current LTS versions. nvm ls shows the installed version marked as default.

On failure: If nvm is not found after installation, source ~/.bashrc or open a new terminal. If the install script fails, download and run it manually after reviewing the script contents.

Step 7: Install Python (via pyenv)

# Install build dependencies
sudo apt install -y make libssl-dev zlib1g-dev libbz2-dev \
  libreadline-dev libsqlite3-dev libncursesw5-dev xz-utils \
  tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

curl https://pyenv.run | bash

# Add to ~/.bashrc
echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc

pyenv install 3.12
pyenv global 3.12

Expected: python --version returns Python 3.12.x. pyenv versions shows the installed version set as global.

On failure: If pyenv install fails with build errors, ensure all build dependencies from the apt install command were installed. Missing libraries (especially libssl-dev or zlib1g-dev) are the most common cause of Python build failures.

Step 8: Configure Shell

Add to ~/.bashrc:

# History
export HISTSIZE=10000
export HISTFILESIZE=20000
export HISTCONTROL=ignoredups:erasedups
shopt -s histappend

# Navigation aliases
alias ll='ls -alF'
alias la='ls -A'
alias ..='cd ..'
alias ...='cd ../..'

# Development paths
export DEV_HOME="/mnt/d/dev/p"
alias dev='cd $DEV_HOME'

# Functions
mkcd() { mkdir -p "$1" && cd "$1"; }

# PATH additions
export PATH="$HOME/bin:$HOME/.local/bin:$PATH"

Expected: After running source ~/.bashrc, all aliases (ll, la, .., dev) work, the mkcd function creates and enters directories, and $DEV_HOME points to the development directory.

On failure: If aliases are not available, verify the additions were appended to ~/.bashrc (not ~/.bash_profile or ~/.profile). Run source ~/.bashrc to reload without opening a new terminal.

Step 9: Set Up Claude Code CLI

# Add Claude CLI to PATH (after installation)
echo 'export PATH="$HOME/.claude/local/node_modules/.bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify
which claude

Expected: which claude returns the path to the Claude Code CLI binary (e.g., ~/.claude/local/node_modules/.bin/claude). Running claude --version prints the installed version.

On failure: If claude is not found, verify the PATH export was added to ~/.bashrc and sourced. Check that Claude Code is actually installed at ~/.claude/local/. If not installed, follow the Claude Code installation instructions first.

Step 10: Cross-Platform Path Reference

Windows	WSL
`C:\Users\Name`	`/mnt/c/Users/Name`
`D:\dev\projects`	`/mnt/d/dev/projects`
`%APPDATA%`	`/mnt/c/Users/Name/AppData/Roaming`

Open Windows Explorer from WSL: explorer.exe .

Expected: The path conversion table is understood and tested: accessing a Windows path from WSL works (e.g., ls /mnt/c/Users/), and explorer.exe . opens Windows Explorer to the current WSL directory.

On failure: If /mnt/c/ is not accessible, verify WSL's automount is configured. Check /etc/wsl.conf for [automount] settings. Run wsl --shutdown and restart if mount points are stale.

Validation

WSL2 running with correct distribution
Git configured with correct identity
SSH key added to GitHub and connection verified
Node.js installed and working
Python installed and working
Shell aliases and functions work
Claude Code CLI accessible

Common Pitfalls

Slow file access on /mnt/: Store frequently accessed projects in WSL filesystem (~/) for better performance. Use /mnt/ for projects shared with Windows tools.
Line endings: core.autocrlf=input prevents CRLF issues. Configure editors to use LF.
Permission issues: Files on /mnt/ may show incorrect permissions. Add to /etc/wsl.conf: [automount]\noptions = "metadata,umask=22,fmask=11"
Windows Defender: Exclude WSL directories from real-time scanning for better performance.

Related Skills

configure-git-repository - detailed Git repository setup
configure-mcp-server - MCP setup requires WSL environment
write-claude-md - configure AI assistant for projects

setup-wsl-dev-environment