Loading...
Complete Claude Code WSL2 installation tutorial in 30 minutes. Configure Node.js, resolve PATH conflicts, and optimize Windows development performance.
This tutorial teaches you to configure Claude Code on Windows Subsystem for Linux in 30 minutes. You'll learn WSL2 installation, Node.js environment setup, and PATH conflict resolution. Perfect for Windows developers who want optimal Claude Code performance without switching operating systems.
Skills and capabilities you'll gain
Complete Linux subsystem setup • Ubuntu 22.04 configuration • Systemd enablement • 20x performance boost
NVM installation and setup • Version 18.0+ configuration • Global package permissions • Build tool setup
VS Code Remote-WSL setup • Cursor IDE configuration • File watching fixes • Hot reload functionality
PATH conflict resolution • Windows Defender exclusions • Memory management • 10x speed improvements
Restart computer and access BIOS settings. Enable Intel VT-x for Intel processors or AMD-V for AMD processors. Save settings and boot Windows normally.
# Check virtualization status in PowerShell
Get-ComputerInfo | Select-Object HyperVRequirementVirtualizationFirmwareEnabled
# Expected output:
# HyperVRequirementVirtualizationFirmwareEnabled : TrueOpen PowerShell as Administrator and run the installation command. The process downloads Ubuntu 22.04 LTS and configures WSL2 kernel automatically.
# Install WSL2 with Ubuntu (PowerShell as Admin)
wsl --install -d Ubuntu-22.04
# Verify installation after restart
wsl --list --verbose
# Output shows: Ubuntu-22.04 Running 2Create wsl.conf file to enable systemd and optimize performance. This configuration enables modern service management required by Claude Code.
# Create WSL configuration file in Ubuntu terminal
sudo nano /etc/wsl.conf
# Add this configuration:
[boot]
systemd=true
[interop]
enabled=true
appendWindowsPath=false
# Restart WSL to apply changes
wsl --shutdown # (run in PowerShell)
wsl # Restart UbuntuLimit WSL memory usage to prevent system slowdown. Creates .wslconfig in Windows user directory with 4GB memory limit.
# Create .wslconfig in Windows (PowerShell)
@"
[wsl2]
memory=4GB
processors=2
swap=2GB
"@ | Out-File -FilePath "$env:USERPROFILE\.wslconfig" -Encoding ASCII
# Apply configuration
wsl --shutdownDownload and install Node Version Manager using the official script. NVM eliminates permission issues that affect 60% of developers.
# Install NVM (in WSL Ubuntu terminal)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Add NVM to shell profile
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bashrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.bashrc
echo '[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"' >> ~/.bashrc
# Reload shell configuration
source ~/.bashrcInstall the latest LTS version meeting Claude Code's Node.js 18.0+ requirement. NVM manages versions without conflicts.
# Install Node.js LTS version
nvm install --lts
nvm use --lts
# Verify installation
node --version # Should show v20.x.x
npm --version # Should show 10.x.x
# Set as default version
nvm alias default nodeSet up user-writable npm directory to avoid permission errors. This prevents EACCES errors during global package installation.
# Create npm global directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
# Add to PATH in .bashrc
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Verify configuration
npm config get prefix # Shows /home/[user]/.npm-globalInstall essential compilation tools for native Node.js modules. Required for packages with C++ bindings used by Claude Code.
# Install build essentials
sudo apt update
sudo apt install -y build-essential python3
# Configure npm Python path
npm config set python python3
# Install node-gyp globally
npm install -g node-gyp
# Verify tools
gcc --version # Should show gcc version
python3 --version # Should show Python 3.xUse native installer for automatic updates and optimal configuration. Avoids npm permission complexities entirely.
# Install Claude Code using native installer
curl -fsSL https://claude.ai/install.sh | bash
# Alternative: NPM installation (if native fails)
npm install -g @anthropic-ai/claude-code
# Verify installation
claude --version # Shows claude-code version
which claude # Shows /home/[user]/.npm-global/bin/claudeVerify all components are properly configured. Claude doctor command checks dependencies and configuration status.
# Run Claude diagnostic
claude doctor
# Expected output:
# ✓ Installation type: native
# ✓ Version: 1.0.44
# ✓ Node.js: v20.x.x
# ✓ Auto-update: enabled
# ✓ IDE detection: VS Code foundSet up Claude Console authentication or API key. Browser opens automatically for OAuth flow during first run.
# Start Claude Code (opens browser for auth)
cd ~/projects/my-project
claude
# Alternative: Use API key directly
export ANTHROPIC_API_KEY='your-api-key-here'
# Add to .bashrc for persistence
echo 'export ANTHROPIC_API_KEY="your-api-key"' >> ~/.bashrcConfigure your preferred development environment
Scenario: Optimal integration with Remote-WSL extension for seamless development.
# Install VS Code Remote-WSL extension
code --install-extension ms-vscode-remote.remote-wsl
# Open project in WSL from Windows
cd ~/projects/my-app
code .
# VS Code server installs automatically
# Full IntelliSense and debugging available{
"terminal.integrated.defaultProfile.linux": "bash",
"terminal.integrated.profiles.linux": {
"bash": {
"path": "/bin/bash",
"icon": "terminal-bash"
}
},
"remote.WSL.fileWatcher.polling": false,
"files.watcherExclude": {
"**/node_modules/**": true
}
}Outcome: Native Linux performance with Windows IDE convenience. File operations run 20x faster than Windows mounts.
Scenario: Alternative AI-powered IDE with WSL support through URI invocation.
# Launch Cursor with WSL project
cursor --folder-uri "vscode-remote://wsl+Ubuntu-22.04/home/user/projects/app"
# Create alias for convenience
echo 'alias cursor-wsl="cursor --folder-uri vscode-remote://wsl+Ubuntu-22.04$(pwd)"' >> ~/.bashrc
source ~/.bashrc
# Now use: cursor-wsl in any project directoryOutcome: Cursor IDE works with WSL projects though integration requires manual configuration.
Scenario: Pure terminal workflow with tmux for persistent sessions.
# Install and configure tmux
sudo apt install -y tmux
# Create tmux configuration
cat > ~/.tmux.conf << 'EOF'
set -g mouse on
set -g history-limit 10000
bind r source-file ~/.tmux.conf
set -g default-terminal "screen-256color"
EOF
# Start tmux session for Claude
tmux new -s claude-dev
claude # Run Claude Code in tmux
# Detach: Ctrl+b, d
# Reattach: tmux attach -t claude-devOutcome: Persistent development sessions survive disconnections. Ideal for remote development scenarios.
Exclude WSL directories from real-time scanning. Reduces file operation latency by 30-50% during builds.
# Add WSL exclusions (PowerShell as Admin)
Add-MpPreference -ExclusionPath "\\wsl$\Ubuntu-22.04"
Add-MpPreference -ExclusionProcess "node.exe"
Add-MpPreference -ExclusionProcess "npm"
# Verify exclusions
Get-MpPreference | Select-Object ExclusionPathMove projects to Linux filesystem for maximum performance. Native ext4 achieves 500MB/s versus 50MB/s on Windows mounts.
# Create project structure in Linux filesystem
mkdir -p ~/dev/projects
cd ~/dev/projects
# Clone or move existing projects
git clone https://github.com/user/project.git
# Never use /mnt/c/ for development
# Bad: cd /mnt/c/Users/name/projects (20x slower)
# Good: cd ~/dev/projects (native speed)
# Check current directory performance
time find . -type f | wc -l # Should complete in <1 secondOptimize git operations based on repository location. Smart configuration improves performance by 5-10x.
# Configure git for WSL
git config --global core.autocrlf input
git config --global core.preloadindex true
git config --global core.fscache true
# Create smart git function
cat >> ~/.bashrc << 'EOF'
git() {
if [[ $(pwd) == /mnt/* ]]; then
/mnt/c/Program\ Files/Git/bin/git.exe "$@"
else
/usr/bin/git "$@"
fi
}
EOF
source ~/.bashrcError Message: WSL 2 requires an update to its kernel component.
Root Cause: Missing or outdated WSL2 kernel after Windows updates.
Solution: Download WSL2 kernel update from Microsoft or run `wsl --update` in PowerShell.
Prevention: Enable automatic WSL updates through Windows Update settings.
#!/bin/bash
# Complete verification script
echo "=== System Check ==="
wsl --status | grep "Default Version: 2"
systemctl --version | head -1
echo "=== Node.js Check ==="
node --version # Should show v20.x.x
npm --version # Should show 10.x.x
which node # Should NOT contain /mnt/c/
echo "=== Claude Check ==="
claude --version
claude doctor
echo "=== Performance Check ==="
cd ~/dev/projects
time ls -la > /dev/null # Should complete in <0.1s
echo "=== IDE Check ==="
code --version 2>/dev/null && echo "VS Code: OK" || echo "VS Code: Not found"
echo "All checks complete!"Continue improving your WSL Claude setup
WSL2 setup is essential for Windows developers using Claude Code. It's particularly effective for full-stack development and Node.js projects. Avoid when using .NET-exclusive workflows.
Ideal scenarios: Web development, AI/ML projects, cross-platform applications
Adapt this tutorial for different needs:
Quick answers to frequent WSL Claude Code questions
Loading reviews...