How to Set Up Claude Code on Windows 11 with WSL2: The Complete Developer Environment Guide

Here is a fact that surprises most Windows developers: the most powerful AI coding assistant available today does not run natively on Windows. Claude Code, Anthropic’s agentic command-line tool that can autonomously write, test, and debug entire applications, was built for Linux and macOS. If you are one of the hundreds of millions of developers on Windows 11, you might think you are locked out. You are not. Thanks to WSL2 — the Windows Subsystem for Linux 2 — you can run a full Linux environment inside Windows with near-native performance, and Claude Code runs flawlessly inside it.

I have been running this exact setup for months now, building production applications, publishing blog posts, and managing infrastructure — all from Claude Code running inside WSL2 on a Windows 11 machine. This guide is everything I wish I had when I started. It covers every step from a fresh Windows 11 installation to running your first AI-assisted project, with every command, every config file, and every expected output included.

By the end of this guide, you will have a complete development environment with Claude Code, Python, Node.js, Docker, VS Code integration, and GPU passthrough for machine learning — all running beautifully on Windows 11.

Let’s get started.

Why WSL2 + Claude Code?

Claude Code is Anthropic’s official agentic CLI tool for software development. Unlike a simple chatbot that gives you code snippets to copy and paste, Claude Code is an autonomous agent. It reads your codebase, writes files, runs commands, installs dependencies, executes tests, fixes errors, and iterates until your project works. It is, by a wide margin, the most capable AI coding tool available in 2026.

Claude Code is available in several forms:

• CLI (terminal) — The original and most powerful version. Runs in your terminal with full access to your filesystem, git, and every tool on your machine.
• Desktop app — Available for Mac and Windows. Provides a graphical interface with the same underlying capabilities.
• Web app — Available at claude.ai/code. No installation required.
• IDE extensions — Integrates directly into VS Code and JetBrains IDEs.

The CLI version is where Claude Code truly shines. It has unrestricted access to your development environment, can run any command, and operates with the same power as you sitting at the terminal. But the CLI runs natively on Linux and macOS only. On Windows, you need WSL2.

WSL2 is not an emulator or a compatibility layer. It runs a real Linux kernel inside a lightweight virtual machine managed by Windows. The result is genuine Linux performance with seamless Windows integration.

Prerequisites

Before we begin, make sure your system meets these requirements. The good news is that most modern Windows 11 machines already qualify.

You will also need to ensure that hardware virtualization is enabled in your BIOS/UEFI. On most modern machines this is already enabled, but if WSL2 installation fails, this is the first thing to check. Look for settings called “Intel VT-x,” “Intel Virtualization Technology,” or “AMD-V” in your BIOS.

You will need a Claude Pro or Claude Max subscription from Anthropic to use Claude Code. As of early 2026, Claude Pro costs $20/month and Claude Max offers higher usage limits at $100/month or $200/month tiers. You can sign up at claude.ai.

Install WSL2 on Windows 11

Installing WSL2 on Windows 11 is remarkably simple — it is literally a single command. Microsoft has come a long way since the early days of WSL.

Open PowerShell as Administrator

Right-click the Start button and select “Terminal (Admin)” or search for “PowerShell” in the Start menu, right-click it, and choose “Run as administrator.” You will see a User Account Control prompt — click “Yes.”

Run the Install Command

In the elevated PowerShell window, run:

wsl --install

This single command does everything: it enables the Virtual Machine Platform, enables the Windows Subsystem for Linux, downloads the Linux kernel, sets WSL2 as the default version, and installs Ubuntu as the default distribution.

You should see output similar to:

Installing: Virtual Machine Platform
Virtual Machine Platform has been installed.
Installing: Windows Subsystem for Linux
Windows Subsystem for Linux has been installed.
Installing: Ubuntu
Ubuntu has been installed.
The requested operation is successful. Changes will not be effective until the system is rebooted.

Choose Your Distribution

If you prefer a specific Ubuntu version instead of the default, you can specify it:

# See all available distributions
wsl --list --online

# Install Ubuntu 22.04 LTS (recommended for stability)
wsl --install -d Ubuntu-22.04

# Or install Ubuntu 24.04 LTS (newer packages)
wsl --install -d Ubuntu-24.04

I recommend Ubuntu 22.04 LTS for most developers. It has the widest package support and the most troubleshooting resources online. Ubuntu 24.04 LTS is also a solid choice if you want newer default packages.

Restart and Initial Setup

After the installation completes, restart your computer. When Windows boots back up, the Ubuntu setup will launch automatically (or you can open it from the Start menu). You will be prompted to create a Linux username and password:

Installing, this may take a few minutes...
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username: developer
New password:
Retype new password:
passwd: password updated successfully
Installation successful!
developer@DESKTOP-ABC123:~$

Verify WSL2 Is Running

Open a new PowerShell window (does not need to be admin) and verify your installation:

wsl --list --verbose

You should see output like:

  NAME            STATE           VERSION
* Ubuntu-22.04    Running         2

The critical column is VERSION — it must say 2. If it says 1, you can convert it:

# Convert an existing WSL1 distro to WSL2
wsl --set-version Ubuntu-22.04 2

# Ensure all future installations use WSL2
wsl --set-default-version 2

Configure WSL2 for Development

Now that WSL2 is running, let’s configure it properly for development work. Open your Ubuntu terminal — you can launch it from the Start menu, type wsl in PowerShell, or open Windows Terminal and select the Ubuntu profile.

Update System Packages

sudo apt update && sudo apt upgrade -y

This will take a few minutes on the first run. It ensures all your system packages are current.

Install Essential Development Tools

sudo apt install -y build-essential git curl wget unzip zip \
  software-properties-common apt-transport-https \
  ca-certificates gnupg lsb-release

This gives you the C/C++ compiler toolchain (needed for many npm and Python packages that compile native extensions), git, curl, wget, and other essential tools.

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 pull.rebase false

The core.autocrlf input setting is especially important in WSL2 — it ensures that line endings are converted to LF (Unix-style) when you commit, preventing issues when working across Windows and Linux filesystems.

Set Up SSH Keys

Generate an SSH key pair for authenticating with GitHub, GitLab, and remote servers:

# Generate a new ED25519 key (recommended)
ssh-keygen -t ed25519 -C "your.email@example.com"

# When prompted for file location, press Enter for the default (~/.ssh/id_ed25519)
# When prompted for passphrase, either enter one or press Enter for none

# Start the SSH agent
eval "$(ssh-agent -s)"

# Add your key to the agent
ssh-add ~/.ssh/id_ed25519

# Display your public key — copy this to GitHub
cat ~/.ssh/id_ed25519.pub

Copy the output and add it to your GitHub account at Settings > SSH and GPG keys > New SSH key. Test the connection:

ssh -T git@github.com
# Expected output: Hi username! You've successfully authenticated...

Configure .wslconfig (Windows Side)

By default, WSL2 will consume up to 50% of your system RAM and all CPU cores. For a better experience, create a .wslconfig file on the Windows side to set limits. Open PowerShell and run:

notepad "$env:USERPROFILE\.wslconfig"

Add the following content (adjust values based on your system):

[wsl2]
# Limit memory (adjust based on your total RAM)
memory=8GB

# Limit CPU cores (adjust based on your CPU)
processors=4

# Swap file size
swap=4GB

# Turn off page reporting to improve performance
pageReporting=false

# Enable nested virtualization (useful for Docker)
nestedVirtualization=true

After saving, restart WSL2 for changes to take effect:

# In PowerShell
wsl --shutdown

# Then relaunch Ubuntu from Start menu or:
wsl

Configure /etc/wsl.conf (Linux Side)

Inside your WSL2 Ubuntu terminal, create or edit the WSL configuration file:

sudo nano /etc/wsl.conf

Add the following:

[automount]
enabled = true
options = "metadata,umask=22,fmask=11"
mountFsTab = false

[network]
generateResolvConf = true

[boot]
systemd = true

[interop]
enabled = true
appendWindowsPath = true

The metadata option in automount allows Linux file permissions to work on Windows-mounted drives. The systemd = true setting enables systemd, which is needed for services like Docker. The appendWindowsPath = true lets you run Windows executables directly from WSL.

Save and exit (Ctrl+O, Enter, Ctrl+X), then restart WSL2 again with wsl --shutdown from PowerShell.

Install Node.js (Required for Claude Code)

Claude Code requires Node.js 18 or later. The best way to install Node.js on Linux is through nvm (Node Version Manager), which lets you install and switch between multiple Node.js versions effortlessly.

Install nvm

# Download and install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Reload your shell configuration
source ~/.bashrc

# Verify nvm is installed
nvm --version
# Expected output: 0.40.1

Install Node.js LTS

# Install the latest LTS version
nvm install --lts

# Verify installation
node --version
# Expected output: v22.x.x (or whatever the current LTS is)

npm --version
# Expected output: 10.x.x

Alternative: Install via NodeSource (Less Recommended)

If you prefer not to use nvm, you can install Node.js directly from the NodeSource repository:

# Add NodeSource repository for Node.js 22.x
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# Install Node.js
sudo apt install -y nodejs

# Verify
node --version
npm --version

This approach works but makes it harder to manage multiple Node.js versions or upgrade later.

Install Claude Code

With Node.js installed, you can now install Claude Code. This is the moment everything comes together.

Install Claude Code Globally

# Install Claude Code globally via npm
npm install -g @anthropic-ai/claude-code

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

If you see a version number, Claude Code is installed and ready to use.

First Launch and Authentication

Navigate to any directory and launch Claude Code for the first time:

# Create a test directory
mkdir -p ~/projects/test-project && cd ~/projects/test-project

# Launch Claude Code
claude

On your first launch, Claude Code will need to authenticate with your Anthropic account. You will see something like:

Welcome to Claude Code!

To get started, you'll need to authenticate with your Anthropic account.

Press Enter to open the authentication page in your browser...

Press Enter. Because WSL2 has Windows interop enabled, it will automatically open a browser window on your Windows desktop. Log in to your Anthropic account and authorize Claude Code. Once approved, you will see a confirmation in your terminal:

Authentication successful!

  ╭──────────────────────────────────────╮
  │ Welcome to Claude Code!              │
  │                                      │
  │ /help for available commands          │
  │ /compact to compact your context      │
  │                                      │
  │ cwd: ~/projects/test-project         │
  ╰──────────────────────────────────────╯

You >

You are now inside the Claude Code interactive session. Your authentication credentials are stored in ~/.claude/ and will persist across sessions.

Keeping Claude Code Updated

Claude Code is updated frequently with new features and improvements. Update it with:

# Update to the latest version
npm update -g @anthropic-ai/claude-code

# Check the new version
claude --version

I recommend updating at least weekly to get the latest capabilities.

Install Python Development Environment

Most developers using Claude Code work with Python at some point. Let’s set up a modern Python environment with uv, the blazing-fast Python package manager that is rapidly becoming the new standard.

Install Python via pyenv

pyenv lets you install and manage multiple Python versions, similar to nvm for Node.js:

# Install pyenv 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

# Install pyenv
curl https://pyenv.run | bash

# Add pyenv to your shell (add these to ~/.bashrc)
echo '' >> ~/.bashrc
echo '# pyenv configuration' >> ~/.bashrc
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

# Reload shell
source ~/.bashrc

# Install Python 3.12 (or latest stable)
pyenv install 3.12
pyenv global 3.12

# Verify
python --version
# Expected output: Python 3.12.x

Install uv — The Modern Python Package Manager

uv is a Python package installer and resolver written in Rust. It is 10-100x faster than pip and replaces pip, pip-tools, pipx, poetry, pyenv, twine, and virtualenv — all in one tool.

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Reload shell to add uv to PATH
source ~/.bashrc

# Verify
uv --version
# Expected output: uv 0.6.x

Quick Start with uv

Here is how to create a new Python project with uv:

# Create a new project
cd ~/projects
uv init my-project
cd my-project

# uv creates: pyproject.toml, .python-version, hello.py, README.md

# Add dependencies
uv add requests fastapi uvicorn

# Run a script
uv run python hello.py

# Sync all dependencies (creates .venv automatically)
uv sync

When Claude Code creates Python projects or installs dependencies, it can use uv seamlessly. The speed difference is transformative — dependency resolution that used to take a minute happens in under a second.

Set Up VS Code with WSL2 Integration

Visual Studio Code has best-in-class WSL2 integration. It runs on Windows but connects transparently to your WSL2 Linux environment, giving you a native editing experience with full Linux tooling underneath.

Install VS Code on Windows

Download VS Code from code.visualstudio.com and install it on Windows. Do not install VS Code inside WSL2 — it is designed to run on the Windows side and connect to WSL2 remotely.

Install the WSL Extension

Open VS Code and install the “WSL” extension (published by Microsoft, extension ID ms-vscode-remote.remote-wsl). This was formerly called “Remote – WSL.”

Connect VS Code to WSL2

The easiest way to open VS Code connected to WSL2 is from inside your WSL2 terminal:

# Navigate to your project in WSL2
cd ~/projects/my-project

# Open VS Code connected to WSL2
code .

VS Code will launch on Windows but you will see “WSL: Ubuntu-22.04” in the bottom-left corner, confirming it is connected to your Linux environment. The terminal inside VS Code will be your WSL2 bash shell. All file operations, extensions, and debugging happen inside Linux.

Install Recommended Extensions (Inside WSL)

Some VS Code extensions need to be installed inside WSL to work correctly. With VS Code connected to WSL2, install these extensions:

• Python (ms-python.python) — Python language support, IntelliSense, debugging
• Pylance (ms-python.vscode-pylance) — Fast Python language server
• Claude Code — VS Code integration for Claude Code (if you want to use Claude Code from inside the editor)
• GitLens (eamodio.gitlens) — Enhanced git visualization
• Docker (ms-azuretools.vscode-docker) — Docker file support and management
• ESLint (dbaeumer.vscode-eslint) — JavaScript/TypeScript linting
• Prettier (esbenp.prettier-vscode) — Code formatting

Optimal VS Code Settings for WSL2

Open your VS Code settings (Ctrl+Shift+P > “Preferences: Open Settings (JSON)”) and add these settings for the best WSL2 experience:

{
  "terminal.integrated.defaultProfile.linux": "bash",
  "terminal.integrated.cwd": "${workspaceFolder}",
  "files.eol": "\n",
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,
  "editor.formatOnSave": true,
  "git.autofetch": true,
  "remote.WSL.fileWatcher.polling": false,
  "search.followSymlinks": false,
  "files.watcherExclude": {
    "**/.git/objects/**": true,
    "**/.git/subtree-cache/**": true,
    "**/node_modules/**": true,
    "**/.venv/**": true,
    "**/venv/**": true
  }
}

Install Docker in WSL2

Docker is an essential tool for modern development, and WSL2 provides excellent Docker support. You have two options: Docker Desktop for Windows or Docker Engine installed directly inside WSL2.

Option A: Docker Desktop for Windows (Easiest)

Docker Desktop for Windows automatically integrates with WSL2. Download it from docker.com, install it, and during setup ensure “Use WSL2 based engine” is checked (it should be by default).

After installation, open Docker Desktop settings and verify that your WSL2 distribution is enabled under Resources > WSL Integration.

Option B: Docker Engine Directly in WSL2 (No License Required)

You can install the Docker engine directly inside WSL2 without Docker Desktop. This is fully open source and free for any use:

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add your user to the docker group (avoids needing sudo)
sudo usermod -aG docker $USER

# Log out and back in for group changes to take effect
# Or run: newgrp docker

# Start Docker service
sudo service docker start

# Verify installation
docker run hello-world

You should see the “Hello from Docker!” message, confirming everything works.

To ensure Docker starts automatically when WSL2 launches, add this to your ~/.bashrc:

# Auto-start Docker daemon
if service docker status 2>&1 | grep -q "is not running"; then
  sudo service docker start > /dev/null 2>&1
fi

For passwordless sudo on the Docker service, run sudo visudo and add:

developer ALL=(ALL) NOPASSWD: /usr/sbin/service docker *

(Replace developer with your WSL2 username.)

Why Docker Matters for Claude Code

Docker is valuable when working with Claude Code for several reasons: you can ask Claude to containerize your applications, run isolated test environments, build CI/CD pipelines, and deploy to cloud platforms like AWS, Google Cloud, or Azure. Claude Code understands Dockerfiles and docker-compose configurations natively and can create, modify, and debug them.

Configure Claude Code for Your Workflow

Claude Code becomes significantly more powerful when you configure it with project-specific context and custom commands. This is where it transforms from a generic AI assistant into a tool that deeply understands your project.

Create a CLAUDE.md File

The CLAUDE.md file is the single most important configuration for Claude Code. Place it in your project root, and Claude Code reads it automatically every time you start a session in that directory. It tells Claude about your project structure, conventions, build commands, and anything else it needs to know.

Here is an example for a Python web application:

# CLAUDE.md — My FastAPI Application

## Project Overview
This is a FastAPI web application with PostgreSQL database,
Redis caching, and Celery task queue.

## Tech Stack
- Python 3.12, FastAPI, SQLAlchemy 2.0, Pydantic v2
- PostgreSQL 16, Redis 7
- Celery for background tasks
- pytest for testing
- Docker Compose for local development

## Key Commands
- `uv run pytest` — Run all tests
- `uv run pytest -x -v` — Run tests, stop on first failure
- `docker compose up -d` — Start all services
- `uv run uvicorn app.main:app --reload` — Start dev server
- `uv run alembic upgrade head` — Run database migrations

## Project Structure
- `app/` — Main application code
- `app/api/` — API route handlers
- `app/models/` — SQLAlchemy models
- `app/schemas/` — Pydantic schemas
- `app/services/` — Business logic
- `tests/` — Test files (mirror app/ structure)
- `alembic/` — Database migrations

## Conventions
- All API endpoints return Pydantic models
- Use dependency injection for database sessions
- Write tests for all new endpoints
- Use async/await for all database operations
- Environment variables in .env (never commit)

Here is another example for a Node.js project:

# CLAUDE.md — Next.js E-commerce Application

## Overview
Next.js 15 e-commerce app with App Router, TypeScript,
Prisma ORM, and Stripe payments.

## Commands
- `npm run dev` — Start development server (port 3000)
- `npm run build` — Production build
- `npm test` — Run Jest tests
- `npx prisma migrate dev` — Run database migrations
- `npx prisma studio` — Open database GUI

## Conventions
- Use Server Components by default, Client Components only when needed
- All data fetching in Server Components or Route Handlers
- Zod for all input validation
- Tailwind CSS for styling (no custom CSS files)
- Prefer named exports over default exports

Set Up Custom Commands

Custom commands let you define reusable workflows that you can invoke with a slash command inside Claude Code. Create the commands directory and add your commands:

# Create the commands directory
mkdir -p .claude/commands

Create a build command at .claude/commands/build.md:

# Build Command

Run the full build pipeline for this project:

1. Install dependencies: `uv sync`
2. Run linting: `uv run ruff check .`
3. Run type checking: `uv run mypy .`
4. Run tests: `uv run pytest -v`
5. If all checks pass, report success
6. If any check fails, fix the issues and re-run

Create a test command at .claude/commands/test.md:

# Test Command

Run the test suite and analyze results:

1. Run `uv run pytest -v --tb=short`
2. If tests fail, analyze the failures
3. Propose fixes for any failing tests
4. After fixing, re-run tests to confirm they pass

Now inside Claude Code, you can type /build or /test and Claude will execute the full workflow defined in the command file.

Configure Project Settings

Create a .claude/settings.json file for project-specific Claude Code settings:

{
  "permissions": {
    "allow": [
      "Bash(uv run *)",
      "Bash(npm run *)",
      "Bash(docker compose *)",
      "Bash(git *)",
      "Bash(pytest *)"
    ]
  }
}

This configuration pre-approves common commands so Claude Code does not need to ask for permission every time it wants to run a build or test. You can add or remove patterns based on your comfort level.

MCP (Model Context Protocol) Servers

Claude Code supports MCP servers, which extend its capabilities with external tools. For example, you can connect it to a database, a file search service, or an API. MCP configuration goes in .claude/settings.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/developer/projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

MCP servers give Claude Code access to external systems in a structured, secure way. The ecosystem is growing rapidly — check the MCP GitHub organization for available servers.

Your First Project with Claude Code

Let’s walk through creating a complete project from scratch using Claude Code. This will demonstrate the agentic workflow — you give Claude a high-level instruction, and it autonomously builds the entire project.

Create the Project

# Create and navigate to a new project directory
mkdir -p ~/projects/my-fastapi-app && cd ~/projects/my-fastapi-app

# Initialize a git repository
git init

# Launch Claude Code
claude

Give Claude Your First Prompt

At the Claude Code prompt, type something like:

You > Create a FastAPI application with the following features:
- User registration and authentication with JWT tokens
- A SQLite database using SQLAlchemy
- CRUD endpoints for a "tasks" resource (each task belongs to a user)
- Input validation with Pydantic models
- Comprehensive pytest tests for all endpoints
- A CLAUDE.md file documenting the project
- Use uv for dependency management

Now watch what happens. Claude Code will:

1. Create a pyproject.toml with all required dependencies
2. Run uv sync to install everything
3. Create the application structure — models, schemas, routes, authentication
4. Write the main application file with all endpoints
5. Create the database models and migration setup
6. Write comprehensive tests
7. Create a CLAUDE.md file documenting the project
8. Run the tests to verify everything works
9. Fix any issues if tests fail

The entire process takes a few minutes. Claude Code will show you each file it creates and each command it runs. You can approve, modify, or reject any action.

Understanding the Interactive Workflow

Claude Code operates in a conversation loop. After it builds the initial project, you can continue giving instructions:

You > Add rate limiting to the API endpoints - max 100 requests
     per minute per user

You > Add a Dockerfile and docker-compose.yml for the project

You > The test for user registration is failing - can you fix it?

You > Refactor the authentication logic into a separate service class

Each time, Claude reads the current state of your codebase, understands what needs to change, makes the modifications, and verifies they work.

Essential Claude Code Commands

Advanced Configuration

Once you have the basics working, these advanced configurations will take your development environment to the next level.

GPU Passthrough for Machine Learning

One of WSL2’s most impressive features is NVIDIA GPU passthrough. You can run CUDA workloads — training neural networks, running inference, using PyTorch or TensorFlow — directly inside WSL2 with near-native GPU performance.

The key requirement: install NVIDIA GPU drivers on the Windows side only. Do not install NVIDIA drivers inside WSL2 — the Windows drivers are automatically shared.

# Step 1: Install NVIDIA drivers on Windows
# Download from: https://www.nvidia.com/download/index.aspx
# Choose your GPU model and install the latest Game Ready or Studio driver

# Step 2: Verify CUDA inside WSL2
nvidia-smi

You should see output showing your GPU model, driver version, and CUDA version:

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 555.42.02    Driver Version: 555.85    CUDA Version: 12.5       |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|===============================+======================+======================|
|   0  NVIDIA GeForce RTX 4090  |   00000000:01:00.0  On |                  N/A |
|  0%   35C    P8    15W / 450W |    512MiB / 24564MiB |      0%      Default |
+-------------------------------+----------------------+----------------------+

# Step 3: Install PyTorch with CUDA support
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

# Step 4: Verify CUDA works in Python
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}'); print(f'GPU: {torch.cuda.get_device_name(0)}')"
# Expected output:
# CUDA available: True
# GPU: NVIDIA GeForce RTX 4090

SSH Key Management Between Windows and WSL2

If you already have SSH keys on the Windows side and want to reuse them in WSL2:

# Copy Windows SSH keys to WSL2
cp -r /mnt/c/Users/YourWindowsUsername/.ssh ~/.ssh

# Fix permissions (critical — SSH will refuse keys with wrong permissions)
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
chmod 644 ~/.ssh/known_hosts 2>/dev/null
chmod 644 ~/.ssh/config 2>/dev/null

Alternatively, you can configure SSH agent forwarding to use the Windows SSH agent from within WSL2. This avoids duplicating keys. Add to your ~/.bashrc:

# Use Windows SSH agent via npiperelay (advanced setup)
# Or simply run ssh-agent in WSL2:
if [ -z "$SSH_AUTH_SOCK" ]; then
  eval "$(ssh-agent -s)" > /dev/null 2>&1
  ssh-add ~/.ssh/id_ed25519 2>/dev/null
fi

File System Performance — The Critical Rule

This is arguably the most important performance tip for WSL2 development, and many guides bury it in a footnote. Here it is, front and center:

Here is why: when you access files on /mnt/c/, every file operation crosses the WSL2-to-Windows filesystem boundary, which adds significant overhead. The Linux filesystem inside WSL2 uses a native ext4 partition that is as fast as a regular Linux installation.

# GOOD — projects on the Linux filesystem
cd ~/projects/my-app
git status  # Instant

# BAD — projects on the Windows filesystem
cd /mnt/c/Users/You/Documents/my-app
git status  # Noticeably slow, especially in large repos

You can still access your Linux files from Windows File Explorer. Just type \\wsl$ in the File Explorer address bar, and you will see your Linux filesystem.

WSL2 Networking

By default, WSL2 automatically forwards ports to Windows. If you start a web server on port 3000 inside WSL2, you can access it at http://localhost:3000 from your Windows browser. This “just works” in most cases.

If automatic port forwarding is not working, you can do it manually from PowerShell:

# Find your WSL2 IP address (from inside WSL2)
hostname -I
# Example output: 172.28.160.2

# Or forward ports manually from PowerShell (admin)
netsh interface portproxy add v4tov4 listenport=3000 listenaddress=0.0.0.0 connectport=3000 connectaddress=172.28.160.2

Back Up Your WSL2 Environment

Once you have your development environment set up perfectly, back it up. WSL2 distributions can be exported and imported as tar files:

# Export your WSL2 distro (from PowerShell)
wsl --export Ubuntu-22.04 D:\Backups\ubuntu-dev-environment.tar

# Import it later (or on another machine)
wsl --import Ubuntu-Dev D:\WSL\Ubuntu-Dev D:\Backups\ubuntu-dev-environment.tar

This creates a complete snapshot of your entire Linux environment — all installed packages, configurations, project files, everything. It is the ultimate insurance policy.

Troubleshooting Common Issues

Even with a straightforward setup, you may encounter issues. Here are the most common problems and their solutions.

If you encounter an issue not listed here, the /doctor command inside Claude Code can diagnose many common problems. You can also run claude --help for a full list of CLI flags and options.

Performance Optimization

A well-tuned WSL2 environment can match or even exceed the performance of a native Linux installation for most development tasks. Here are the key optimizations.

Recommended .wslconfig Settings

Linux vs Windows Filesystem Performance

To illustrate why the filesystem choice matters, here are approximate benchmarks for common operations in a medium-sized project (50,000 files including node_modules):

Additional Performance Tips

• Disable Windows Defender scanning for WSL2 directories. Add the WSL2 virtual disk path to Windows Defender exclusions: %LOCALAPPDATA%\Packages\CanonicalGroupLimited*
• Use .gitignore aggressively. Exclude node_modules/, .venv/, __pycache__/, and other generated directories from git tracking.
• Disable VS Code file watchers for large directories. Use the files.watcherExclude setting shown earlier.
• Keep WSL2 updated. Run wsl --update from PowerShell periodically for kernel and performance improvements.
• Use wsl --shutdown when not using WSL2. This frees all the memory WSL2 was using back to Windows.

Alternative: Claude Code Desktop App and VS Code Extension

While this guide focuses on the Claude Code CLI in WSL2 — which offers the most power and flexibility — there are other ways to use Claude Code on Windows.

My recommendation: use the CLI in WSL2 as your primary development tool, and keep the desktop app or VS Code extension available for quick tasks when you do not need the full Linux environment. They can coexist on the same machine without any conflicts.

The desktop app is particularly useful when you want to quickly ask Claude Code a question about your code without opening a terminal, or when you are doing more exploratory work that does not require building and running code.

Conclusion

You now have a world-class development environment running on Windows 11. Let’s recap what we built:

• WSL2 providing a full Ubuntu Linux environment with near-native performance
• Claude Code — Anthropic’s agentic AI coding assistant, installed and authenticated
• Node.js via nvm for JavaScript/TypeScript development and Claude Code itself
• Python with pyenv and uv for modern, blazing-fast Python development
• VS Code seamlessly connected to WSL2 for the best editing experience
• Docker for containerized development and deployment
• GPU passthrough for machine learning workloads
• Custom commands and CLAUDE.md configuration for project-specific AI assistance

This setup eliminates the historical disadvantage Windows developers faced when it came to Linux-native tooling. With WSL2, you genuinely get the best of both worlds: the Windows desktop experience you are comfortable with and the full Linux development environment that tools like Claude Code, Docker, and the broader open-source ecosystem are built for.

The key points to remember going forward:

1. Keep projects on the Linux filesystem (~/projects/) for maximum performance
2. Update Claude Code regularly — new features ship weekly
3. Write a good CLAUDE.md for every project — it dramatically improves Claude’s output
4. Use custom commands to codify your workflows and make them repeatable
5. Back up your WSL2 environment once it is set up the way you like it

The combination of Claude Code and a properly configured development environment is genuinely transformative. Tasks that used to take hours — scaffolding a new project, writing tests, debugging obscure errors, setting up CI/CD — now take minutes. And because Claude Code runs locally in your terminal with full access to your tools, it works with your existing workflow rather than replacing it.

Welcome to the future of development on Windows. Now go build something amazing.

References

• Claude Code Documentation — Anthropic
• Install WSL — Microsoft Learn
• WSL Configuration — Microsoft Learn
• Developing in WSL — Visual Studio Code Documentation
• Docker Desktop WSL2 Backend — Docker Documentation
• CUDA on WSL — NVIDIA Documentation
• nvm — Node Version Manager (GitHub)
• uv — Python Package Manager Documentation
• pyenv — Python Version Manager (GitHub)
• Model Context Protocol (MCP) — Official Site