How to Use Claude Code with WSL2 on Windows 2026

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Workflow

Install and configure Claude Code inside WSL2 on Windows for a native Linux development experience. Handle Windows-Linux path translation, SSH key sharing, and VS Code Remote integration so Claude Code operates seamlessly across both environments.

Expected time: 20 minutes Prerequisites: Windows 11 with WSL2 enabled, Ubuntu 22.04+ distribution installed

Setup

1. Install Node.js in WSL2

# Inside WSL2 (open Windows Terminal → Ubuntu)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify
node --version
# Expected: v20.x.x
npm --version
# Expected: 10.x.x

2. Install Claude Code

npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version
# Expected: claude-code x.x.x

3. Configure Environment Variables

# Add to ~/.bashrc or ~/.zshrc
cat >> ~/.bashrc << 'EOF'

# Claude Code configuration
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# Fix Windows/Linux path issues for Claude Code
export DONT_PROMPT_WSL_INSTALL=1

# Ensure Claude Code uses Linux paths
export CLAUDE_CODE_CWD_MODE="linux"
EOF

source ~/.bashrc

4. Set Up SSH Key Sharing Between Windows and WSL2

# Copy Windows SSH keys to WSL2 (if you have existing keys)
cp -r /mnt/c/Users/YourUser/.ssh ~/.ssh
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_*
chmod 644 ~/.ssh/*.pub

# Or generate new keys specifically for WSL2
ssh-keygen -t ed25519 -C "[email protected]"

5. Configure Git for Cross-Environment Work

# Set Git to handle line endings correctly
git config --global core.autocrlf input
git config --global core.eol lf

# Set your identity
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

6. Integrate with VS Code Remote - WSL

# Install VS Code Server in WSL (happens automatically when you open VS Code)
# From Windows: code .  (in a WSL directory)
# This launches VS Code connected to WSL2

# In VS Code terminal (which runs in WSL2):
claude
# Claude Code now has access to your WSL2 Linux filesystem

7. Verify

# Test Claude Code works in WSL2
claude --print "What OS am I running on? Show uname output."
# Expected output:
# Linux [hostname] 5.15.x-microsoft-standard-WSL2

# Test file access
claude --print "List files in my home directory"
# Expected: Lists your WSL2 home directory contents

Usage Example

Setting up a complete development workflow with Claude Code in WSL2:

# Create a project in WSL2 filesystem (NOT /mnt/c/ for performance)
mkdir -p ~/projects/my-api
cd ~/projects/my-api
git init
npm init -y

# Start Claude Code
claude

> Set up an Express TypeScript project with:
> - src/ directory with proper tsconfig
> - ESLint + Prettier config
> - Docker Compose with PostgreSQL
> - Jest for testing
> - A .env.example file

Claude Code generates the project structure:

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "rootDir": "./src",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

# docker-compose.yml
version: "3.9"
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: devpass
      POSTGRES_DB: myapi
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://dev:devpass@postgres:5432/myapi
    depends_on:
      - postgres
    volumes:
      - .:/app
      - /app/node_modules

volumes:
  pgdata:

Working with Windows paths when needed:

# Access Windows files from WSL2 (slower, avoid for projects)
ls /mnt/c/Users/YourUser/Documents/

# Tell Claude Code about a Windows file
claude --print "Read /mnt/c/Users/YourUser/Documents/spec.pdf and summarize it"

# Better: Copy to WSL2 first for performance
cp /mnt/c/Users/YourUser/Documents/spec.pdf ~/projects/docs/

Common Issues

Why This Matters

WSL2 gives Windows developers the Linux environment Claude Code expects. Projects run at native Linux filesystem speed while maintaining access to Windows GUI tools like VS Code, browsers, and design applications.