---

name: setup-wsl-dev-environment locale: caveman-ultra source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-05-03" description: > WSL2 dev env on Windows: shell config, tools, Git, SSH keys, Node.js, Python, cross-platform paths. Use → new Windows machine, first WSL2 setup, add tools to existing WSL, or WSL+Windows workflows. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: general complexity: intermediate language: multi tags: wsl, windows, linux, development, setup

Set Up WSL Dev Env

WSL2 dev env → cross-platform work.

Use When

• New Windows machine → dev setup
• First WSL2 config
• Add dev tools → existing WSL
• WSL + Windows tool workflows

In

• Required: Windows 10/11 w/ WSL2
• Optional: Linux distro (default: Ubuntu)
• Optional: Langs (Node, Python, R)
• Optional: Extra tools (Docker, tmux, fzf)

Do

Step 1: Install WSL2

PowerShell (Admin):

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

Reboot if asked. Ubuntu = default.

Got: wsl --list --verbose → distro under WSL v2. wsl → Linux shell.

If err: Install fails → enable "Virtual Machine Platform" + "Windows Subsystem for Linux" via optionalfeatures.exe. Old Win10 → kernel update from MS.

Step 2: WSL Resource Limits

~/.wslconfig in Windows home:

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

Got: .wslconfig in Windows home (e.g. C:\Users\Name\.wslconfig). After wsl --shutdown + restart → limits applied.

If err: No effect → file in wrong dir (Windows home, not WSL home). wsl --shutdown + reopen.

Step 3: Update + 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

Aliases:

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

Got: All install. git --version, jq --version, rg --version, tree work.

If err: apt install fails → sudo apt update first. Pkg not found → check Ubuntu ver, alt sources (snap, cargo, manual).

Step 4: 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

Got: git config --list → name, email, branch (main), autocrlf (input), editor.

If err: Not applied → used --local not --global. Check ~/.gitconfig.

Step 5: 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

Got: ssh -T git@github.com → "Hi username! You've successfully authenticated." Keys at ~/.ssh/id_ed25519{,.pub}.

If err: Auth fails → pubkey added to GitHub? ssh-agent running? ssh-add -l → key loaded? Add eval "$(ssh-agent -s)" → ~/.bashrc.

Step 6: Node.js (nvm)

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

Got: node --version + npm --version → LTS. nvm ls → default marked.

If err: nvm not found → source ~/.bashrc or new term. Script fails → review + run manually.

Step 7: Python (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

Got: python --version → 3.12.x. pyenv versions → set global.

If err: Build err → missing deps from apt install. libssl-dev | zlib1g-dev = most common cause.

Step 8: Shell

~/.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"

Got: After source ~/.bashrc → aliases (ll, la, .., dev) work, mkcd creates+enters, $DEV_HOME set.

If err: Aliases missing → check appended to ~/.bashrc (not ~/.bash_profile | ~/.profile). source ~/.bashrc.

Step 9: 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

Got: which claude → path (e.g. ~/.claude/local/node_modules/.bin/claude). claude --version → ver.

If err: Not found → PATH export in ~/.bashrc + sourced? Installed at ~/.claude/local/? Else install first.

Step 10: Cross-Platform Paths

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

Explorer from WSL: explorer.exe .

Got: Path table understood + tested (ls /mnt/c/Users/, explorer.exe . opens current dir).

If err: /mnt/c/ inaccessible → automount config? /etc/wsl.conf [automount]. wsl --shutdown + restart.

Check

• WSL2 running w/ correct distro
• Git config'd w/ identity
• SSH key on GitHub + verified
• Node.js works
• Python works
• Shell aliases + funcs work
• Claude Code CLI accessible

Traps

• Slow /mnt/ access: Hot projects → WSL fs (~/). /mnt/ only for Windows-shared.
• Line endings: core.autocrlf=input prevents CRLF. Editors → LF.
• Permissions: /mnt/ shows wrong perms → /etc/wsl.conf [automount]\noptions = "metadata,umask=22,fmask=11".
• Windows Defender: Exclude WSL dirs from real-time scan.

→

• configure-git-repository — Git repo setup
• configure-mcp-server — MCP needs WSL env
• write-claude-md — configure AI assistant