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

A fact that surprises many Windows developers is that the most capable AI coding assistant currently available 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. Windows 11 users may suppose they are excluded. They are not. WSL2 (the Windows Subsystem for Linux 2) provides a full Linux environment inside Windows with near-native performance, and Claude Code operates reliably within it.

The configuration described here has been used continuously for several months in production work, blog publication, and infrastructure management, with Claude Code running inside WSL2 on Windows 11. This guide aggregates the material that would have been useful at the outset. It covers every step from a fresh Windows 11 installation to the execution of a first AI-assisted project, with every command, configuration file, and expected output included.

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

The following sections present the procedure in order.

Why WSL2 with Claude Code?

Claude Code is Anthropic’s official agentic CLI tool for software development. Unlike a simple chatbot that provides code snippets for manual copying, Claude Code operates as an autonomous agent. It reads the codebase, writes files, runs commands, installs dependencies, executes tests, fixes errors, and iterates until the project works as intended. By a substantial margin, it is the most capable AI coding tool available in 2026.

Claude Code is available in several forms:

• CLI (terminal): the original and most capable version. It runs in the terminal with full access to the filesystem, git, and every tool on the machine.
• Desktop app: available for macOS and Windows. It provides a graphical interface with the same underlying capabilities.
• Web app: available at claude.ai/code. No installation is required.
• IDE extensions: integrate directly with VS Code and JetBrains IDEs.

The CLI version is the most capable form of Claude Code. It has unrestricted access to the development environment, can run any command, and operates with the same authority as a developer at the terminal. The CLI runs natively only on Linux and macOS. On Windows, WSL2 is required.

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 beginning, the system should be confirmed to meet the requirements below. Most modern Windows 11 machines already do so.

Hardware virtualization must also be enabled in the BIOS/UEFI. On most modern machines, this is already enabled; however, if WSL2 installation fails, this is the first item to verify. The relevant BIOS setting is termed “Intel VT-x,” “Intel Virtualization Technology,” or “AMD-V.”

A Claude Pro or Claude Max subscription from Anthropic is required to use Claude Code. As of early 2026, Claude Pro costs $20 per month, and Claude Max offers higher usage limits at the $100 and $200 per month tiers. Registration is available at claude.ai.

Install WSL2 on Windows 11

Installation of WSL2 on Windows 11 is straightforward and requires only a single command. Microsoft has substantially refined the installation experience since the original WSL release.

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.” A User Account Control prompt will appear; click “Yes.”

Run the Install Command

In the elevated PowerShell window, run:

wsl --install

This single command performs the full installation: 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.

The output should resemble the following:

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.

Choosing a Distribution

If a specific Ubuntu version is preferred over the default, it can be specified as follows:

# 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

Ubuntu 22.04 LTS is recommended for most developers. It has the widest package support and the largest body of troubleshooting material online. Ubuntu 24.04 LTS is also a sound choice for users who require newer default packages.

Restart and Initial Setup

After the installation completes, the computer should be restarted. When Windows boots again, the Ubuntu setup launches automatically (or can be opened from the Start menu). The user is 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 That WSL2 Is Running

A new PowerShell window (administrator privileges not required) can be used to verify the installation:

wsl --list --verbose

The output should resemble the following:

  NAME            STATE           VERSION
* Ubuntu-22.04    Running         2

The important column is VERSION, which must read 2. If it reads 1, conversion is possible:

# 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

With WSL2 running, the next step is to configure it for development work. The Ubuntu terminal can be launched from the Start menu, by typing wsl in PowerShell, or by opening Windows Terminal and selecting the Ubuntu profile.

Update System Packages

sudo apt update && sudo apt upgrade -y

The first run requires several minutes. This step ensures that all 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 command installs the C/C++ compiler toolchain (required 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 particularly important in WSL2; it ensures that line endings are converted to LF (Unix-style) on commit, which prevents difficulties when working across Windows and Linux filesystems.

Set Up SSH Keys

Generate an SSH key pair for authentication 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

The output should be copied and added to the GitHub account at Settings > SSH and GPG keys > New SSH key. Connectivity can be tested as follows:

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

Configure .wslconfig on the Windows Side

By default, WSL2 consumes up to 50% of system RAM and all CPU cores. For a better experience, a .wslconfig file should be created on the Windows side to set limits. The procedure is to open PowerShell and run:

notepad "$env:USERPROFILE\.wslconfig"

The following content should be added (values should be adjusted to match the 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, WSL2 should be restarted for changes to take effect:

# In PowerShell
wsl --shutdown

# Then relaunch Ubuntu from Start menu or:
wsl

Configure /etc/wsl.conf on the Linux Side

Within the WSL2 Ubuntu terminal, the WSL configuration file should be created or edited:

sudo nano /etc/wsl.conf

The following content should be added:

[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 permits Linux file permissions to function on Windows-mounted drives. The systemd = true setting enables systemd, which is required for services such as Docker. The appendWindowsPath = true setting permits Windows executables to be run directly from WSL.

The file should be saved and closed (Ctrl+O, Enter, Ctrl+X), and WSL2 should then be restarted via wsl --shutdown in PowerShell.

Install Node.js (Required for Claude Code)

Claude Code requires Node.js 18 or later. The recommended method of installing Node.js on Linux is through nvm (Node Version Manager), which permits the installation of multiple Node.js versions and rapid switching between them.

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 nvm is not preferred, Node.js can be installed 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 functions but complicates the management of multiple Node.js versions and subsequent upgrades.

Install Claude Code

With Node.js installed, Claude Code can now be installed. The remaining configuration follows from this step.

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 a version number is displayed, Claude Code is installed and ready for 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 first launch, Claude Code must authenticate with the user’s Anthropic account. A prompt similar to the following will appear:

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...

Pressing Enter triggers WSL2’s Windows interop, which opens a browser window on the Windows desktop. The user then logs in to the Anthropic account and authorizes Claude Code. Upon approval, the terminal displays a confirmation:

Authentication successful!

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

You >

The user is now within the Claude Code interactive session. Authentication credentials are stored in ~/.claude/ and persist across sessions.

Keeping Claude Code Updated

Claude Code receives frequent updates with new features and improvements. The update procedure is:

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

# Check the new version
claude --version

Weekly updates are recommended to obtain the most recent capabilities.

Install Python Development Environment

Most developers using Claude Code work with Python at some point. The following sections describe the configuration of a modern Python environment using uv, a rapid Python package manager that is becoming a de facto standard.

Install Python via pyenv

pyenv permits the installation and management of multiple Python versions, analogous 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: A Modern Python Package Manager

uv is a Python package installer and resolver written in Rust. It is 10 to 100 times faster than pip and replaces pip, pip-tools, pipx, poetry, pyenv, twine, and virtualenv in a single 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

The procedure for creating a new Python project with uv is as follows:

# 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

Claude Code uses uv seamlessly when creating Python projects or installing dependencies. The speed difference is substantial; dependency resolution that previously required a minute now completes in under a second.

Set Up VS Code with WSL2 Integration

Visual Studio Code provides best-in-class WSL2 integration. It runs on Windows but connects transparently to the WSL2 Linux environment, providing a native editing experience with full Linux tooling.

Install VS Code on Windows

VS Code should be downloaded from code.visualstudio.com and installed on Windows. VS Code should not be installed within WSL2; it is designed to run on the Windows side and connect to WSL2 remotely.

Install the WSL Extension

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

Connect VS Code to WSL2

The most direct method of opening VS Code with a WSL2 connection is from within the WSL2 terminal:

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

# Open VS Code connected to WSL2
code .

VS Code launches on Windows, and the bottom-left corner displays “WSL: Ubuntu-22.04,” confirming the Linux connection. The terminal inside VS Code is the WSL2 bash shell. All file operations, extensions, and debugging occur within Linux.

Install Recommended Extensions Inside WSL

Some VS Code extensions must be installed within WSL to function correctly. With VS Code connected to WSL2, the following extensions should be installed:

• Python (ms-python.python): Python language support, IntelliSense, debugging
• Pylance (ms-python.vscode-pylance): a fast Python language server
• Claude Code: VS Code integration for Claude Code (for users who wish to invoke Claude Code from within the editor)
• GitLens (eamodio.gitlens): enhanced git visualization
• Docker (ms-azuretools.vscode-docker): Dockerfile support and management
• ESLint (dbaeumer.vscode-eslint): JavaScript/TypeScript linting
• Prettier (esbenp.prettier-vscode): code formatting

Optimal VS Code Settings for WSL2

The VS Code settings can be opened (Ctrl+Shift+P, then “Preferences: Open Settings (JSON)”) and the following settings added for an optimal 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 a useful tool for modern development, and WSL2 provides strong Docker support. Two options are available: Docker Desktop for Windows or the Docker Engine installed directly inside WSL2.

Option A: Docker Desktop for Windows (Simplest)

Docker Desktop for Windows integrates automatically with WSL2. It should be downloaded from docker.com and installed. During setup, “Use WSL2 based engine” should be checked (it is enabled by default).

After installation, Docker Desktop settings should be opened to verify that the WSL2 distribution is enabled under Resources > WSL Integration.

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

The Docker engine can be installed directly inside WSL2 without Docker Desktop. This option 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

The “Hello from Docker!” message should appear, confirming a working installation.

To ensure that Docker starts automatically when WSL2 launches, the following should be added to ~/.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, sudo visudo should be executed and the following line added:

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

(Replace developer with your WSL2 username.)

The Significance of Docker for Claude Code

Docker is valuable when working with Claude Code for several reasons: Claude can be directed to containerize applications, run isolated test environments, build CI/CD pipelines, and deploy to cloud platforms such as 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 the Workflow

Claude Code becomes substantially more capable when configured with project-specific context and custom commands. This is the point at which it transforms from a generic AI assistant into a tool that deeply understands the project.

Create a CLAUDE.md File

The CLAUDE.md file is the single most important Claude Code configuration. It should be placed in the project root, and Claude Code reads it automatically whenever a session begins in that directory. It informs Claude about project structure, conventions, build commands, and any other context that is required.

An example for a Python web application is the following:

# 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)

A further example for a Node.js project is the following:

# 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 permit the definition of reusable workflows that can be invoked with a slash command inside Claude Code. The commands directory should be created and commands added:

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

A build command should be created 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

A test command should be created 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

Within Claude Code, typing /build or /test directs Claude to execute the full workflow defined in the command file.

Configure Project Settings

A .claude/settings.json file should be created 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 that Claude Code does not request permission for routine build or test operations. Patterns can be added or removed based on the user’s preferred level of caution.

MCP (Model Context Protocol) Servers

Claude Code supports MCP servers, which extend its capabilities with external tools. For example, connections to a database, a file-search service, or an API can be configured. MCP configuration resides 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 provide Claude Code with structured, secure access to external systems. The ecosystem is expanding rapidly; available servers can be reviewed at the MCP GitHub organization.

A First Project with Claude Code

The following section describes the creation of a complete project from scratch using Claude Code. The agentic workflow proceeds as follows: the user provides a high-level instruction, and Claude autonomously constructs the 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

Provide Claude with the First Prompt

At the Claude Code prompt, the following can be typed:

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

The resulting behaviour is as follows. Claude Code will:

1. Create a pyproject.toml containing all required dependencies
2. Run uv sync to install all packages
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 functionality
9. Address any failures that occur

The full process requires several minutes. Claude Code displays each file it creates and each command it runs. Every action can be approved, modified, or rejected.

Understanding the Interactive Workflow

Claude Code operates in a conversation loop. After the initial project has been built, further instructions can be provided:

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

In each case, Claude reads the current state of the codebase, determines what must change, makes the modifications, and verifies that they function.

Essential Claude Code Commands

Advanced Configuration

Once the basic configuration is operational, the following advanced settings will refine the development environment further.

GPU Passthrough for Machine Learning

One of the most notable features of WSL2 is NVIDIA GPU passthrough. CUDA workloads, neural-network training, inference, and PyTorch or TensorFlow use can occur directly inside WSL2 with near-native GPU performance.

The principal requirement is to install NVIDIA GPU drivers on the Windows side only. NVIDIA drivers should not be installed inside WSL2; the Windows drivers are shared automatically.

# 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

The output should display the 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 SSH keys already exist on the Windows side and should be reused 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, SSH agent forwarding can be configured to use the Windows SSH agent from within WSL2. This approach avoids duplicating keys. The following should be added to ~/.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

Filesystem Performance: The Critical Rule

This is arguably the most important performance consideration for WSL2 development. Many guides relegate it to a footnote; it is presented here prominently:

The explanation is as follows: accessing files on /mnt/c/ causes every file operation to cross the WSL2-to-Windows filesystem boundary, which imposes substantial overhead. The Linux filesystem inside WSL2 uses a native ext4 partition that performs at the speed of 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

Linux files remain accessible from Windows File Explorer. Typing \\wsl$ in the File Explorer address bar displays the Linux filesystem.

WSL2 Networking

By default, WSL2 automatically forwards ports to Windows. A web server started on port 3000 inside WSL2 can be accessed at http://localhost:3000 from the Windows browser. This behaviour functions automatically in most cases.

If automatic port forwarding does not operate, manual forwarding from PowerShell is possible:

# 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 the WSL2 Environment

Once the development environment has been configured satisfactorily, it should be backed 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 the entire Linux environment, including all installed packages, configurations, and project files. It provides comprehensive protection against data loss.

Troubleshooting Common Issues

Even with a straightforward setup, issues may occur. The following table summarizes the most common problems and their solutions.

If an issue not listed here is encountered, the /doctor command inside Claude Code can diagnose many common problems. claude --help displays a full list of CLI flags and options.

Performance Optimization

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

Recommended .wslconfig Settings

Linux and Windows Filesystem Performance Compared

To illustrate the importance of filesystem choice, the following table presents approximate benchmarks for common operations in a medium-sized project (50,000 files including node_modules):

Additional Performance Considerations

• Disable Windows Defender scanning for WSL2 directories. The WSL2 virtual disk path should be added to Windows Defender exclusions: %LOCALAPPDATA%\Packages\CanonicalGroupLimited*
• Use .gitignore assertively. node_modules/, .venv/, __pycache__/, and other generated directories should be excluded from git tracking.
• Disable VS Code file watchers for large directories. The files.watcherExclude setting described earlier should be used.
• Keep WSL2 updated. wsl --update should be run from PowerShell periodically to obtain kernel and performance improvements.
• Use wsl --shutdown when WSL2 is not in use. This returns to Windows the memory previously allocated to WSL2.

Alternative: Claude Code Desktop App and VS Code Extension

Although this guide focuses on the Claude Code CLI in WSL2, which provides the greatest capability and flexibility, other means of using Claude Code on Windows are available.

The recommended approach is to use the CLI in WSL2 as the primary development tool while keeping the desktop app or VS Code extension available for brief tasks that do not require the full Linux environment. The tools coexist on the same machine without conflict.

The desktop app is particularly useful for brief questions about code without opening a terminal, or for exploratory work that does not require building and running code.

Conclusion

The configuration described above constitutes a comprehensive development environment running on Windows 11. The components are as follows:

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

This configuration eliminates the historical disadvantage that Windows developers faced with respect to Linux-native tooling. With WSL2, the user obtains both the familiar Windows desktop experience and the full Linux development environment for which tools such as Claude Code, Docker, and the broader open-source ecosystem are designed.

Key recommendations going forward are the following:

1. Keep projects on the Linux filesystem (~/projects/) for maximum performance.
2. Update Claude Code regularly; new features are released frequently.
3. Write a thorough CLAUDE.md for every project; it substantially improves Claude’s output.
4. Use custom commands to codify workflows and make them repeatable.
5. Back up the WSL2 environment once it has been configured to satisfaction.

The combination of Claude Code and a properly configured development environment is substantially transformative. Tasks that previously required hours, such as scaffolding a new project, writing tests, debugging obscure errors, or setting up CI/CD, now require minutes. Because Claude Code runs locally in the terminal with full access to development tools, it integrates with existing workflows rather than replacing them.

This configuration represents a substantial advance in development on Windows.

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