Slow file operations on /mnt/c/: Always keep projects in the WSL2 Linux filesystem (~/projects/), not on the Windows mount. Performance difference is 10-50x. npm global install permission errors: Run mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global and add ~/.npm-global/bin...

How to Use Claude Code with WSL2 (2026)

Last updated: April 21, 2026

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

# 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 "your-email@example.com"

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 "your-email@example.com"

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

Slow file operations on /mnt/c/: Always keep projects in the WSL2 Linux filesystem (~/projects/), not on the Windows mount. Performance difference is 10-50x.
npm global install permission errors: Run mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global and add ~/.npm-global/bin to your PATH.
VS Code terminal shows Windows path: Ensure you opened VS Code via WSL (code . from WSL terminal), not from Windows Explorer. Check the bottom-left corner shows “WSL: Ubuntu”.

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.

Get started → Generate your project setup with our Project Starter.

Configure permissions → Build your settings with our Permission Configurator.

Try it: Paste your error into our Error Diagnostic for an instant fix.

Frequently Asked Questions

What is the minimum setup required?

You need Claude Code installed (Node.js 18+), a project with a CLAUDE.md file, and the relevant toolchain for your project type (e.g., npm for JavaScript, pip for Python). The CLAUDE.md file should describe your project structure, conventions, and common commands so Claude Code can work effectively.

How long does the initial setup take?

For a typical project, initial setup takes 10-20 minutes. This includes creating the CLAUDE.md file, configuring .claude/settings.json for permissions, and running a test task to verify everything works. Subsequent sessions start immediately because the configuration persists.

Can I use this with a team?

Yes. Commit your .claude/ directory and CLAUDE.md to version control so the entire team uses the same configuration. Each developer can add personal preferences in ~/.claude/settings.json (user-level) without affecting the project configuration. Review CLAUDE.md changes in pull requests like any other configuration file.

What if Claude Code produces incorrect output?

First check that your CLAUDE.md accurately describes your project conventions. Incorrect or outdated context is the most common cause of wrong output. If the output is still wrong, provide feedback in the same session — Claude Code learns from corrections within a conversation. For persistent issues, add explicit rules to CLAUDE.md (e.g., “Always use single quotes” or “Never modify files in the config/ directory”).

Best Practices

Start with a clear CLAUDE.md. Describe your project structure, tech stack, coding conventions, and common commands in under 300 words. This single file has the largest impact on Claude Code’s accuracy and efficiency.
Use skills for domain knowledge. Move detailed reference information (API routes, database schemas, deployment procedures) into .claude/skills/ files. This keeps CLAUDE.md concise while making specialized knowledge available when needed.
Review changes before committing. Always run git diff after Claude Code makes changes. Verify the edits are correct, match your project style, and do not introduce unintended side effects. This habit prevents compounding errors across sessions.
Set up permission guardrails. Configure .claude/settings.json with explicit allow and deny lists. Allow your standard development commands (test, build, lint) and deny destructive operations (rm -rf, git push –force, database drops).
Keep sessions focused. Give Claude Code one clear task per prompt. Multi-step requests like “refactor auth, add tests, and update docs” produce better results when broken into three separate prompts, each building on the previous result.