Claude Code on Windows: Complete Installation Guide (2026)

Prerequisites

Before installing, confirm these requirements:

• Windows version: Windows 10 version 2004+ (Build 19041) or Windows 11
• RAM: 8 GB minimum (16 GB recommended if using WSL2 or Docker)
• Disk: 2 GB free for WSL2 + Claude Code, 500 MB for native install
• Account: Claude Pro ($20/month), Max ($100-200/month), Teams, Enterprise, or Anthropic Console with API credits

The free Claude.ai plan does not include Claude Code access. You need a paid account.

Node.js (only for npm method)

The native installer and Docker methods do not require Node.js. If you plan to use the npm installation path inside WSL2, install Node.js 18+ using one of these methods:

# Option 1: nvm (recommended, avoids permission issues)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 22

# Option 2: apt (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

On native Windows, install via winget install OpenJS.NodeJS.LTS, the Node.js installer, or choco install nodejs-lts if you use Chocolatey.

Method 1: WSL2 (Recommended)

WSL2 runs a real Linux kernel on Windows. Claude Code operates exactly as it would on a native Linux machine: file watching, git hooks, shell integration, MCP servers, everything works.

Step 1: Install WSL2

Open PowerShell as Administrator and run:

wsl --install

This installs WSL2 with Ubuntu as the default distribution. Restart your computer when prompted. After reboot, Ubuntu opens and asks you to create a Linux username and password.

Step 2: Install Claude Code inside WSL2

Open your WSL2 terminal (search "Ubuntu" in the Start menu) and run:

# Native installer (recommended, no Node.js needed)
curl -fsSL https://claude.ai/install.sh | bash

# Or via npm if you prefer
npm install -g @anthropic-ai/claude-code

Step 3: Verify the installation

# Check claude is on your PATH
which claude

# Start Claude Code
cd ~/projects/your-project
claude

On first launch, Claude Code opens your browser for authentication. Authorize it with your Anthropic account. The session token is stored in your WSL2 home directory.

Method 2: Native Windows (PowerShell)

The native installer runs Claude Code directly on Windows without WSL2 or Docker. Good for quick setup, but with some limitations.

# Run in PowerShell (not CMD)
irm https://claude.ai/install.ps1 | iex

After installation, open a new PowerShell window and run claude. The command should be available globally.

Limitations of native Windows

• File watching: Some file system events behave differently on NTFS than ext4. Claude Code may not detect external file changes as reliably.
• Shell integration: Bash-specific features (prompt integration, shell hooks) are not available in PowerShell.
• MCP servers: Servers that assume Unix paths or use Unix sockets may not work natively. Check each server's Windows compatibility.
• Line endings: Windows uses CRLF by default. Configure Git to use LF (see Common Issues below).

For basic code editing, asking questions about your codebase, and running commands, the native install works fine. If you run into edge cases, switch to WSL2.

Method 3: Docker on Windows

Docker gives you a fully isolated Linux environment without installing WSL2 system-wide. Install Docker Desktop for Windows first (it uses WSL2 as its backend, but manages it automatically).

# Pull and run with your project mounted
docker run -it --rm \
  -v "$(pwd):/workspace" \
  -w /workspace \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  node:22-slim \
  bash -c "npm install -g @anthropic-ai/claude-code && claude"

# Or use the native installer inside the container
docker run -it --rm \
  -v "$(pwd):/workspace" \
  -w /workspace \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  ubuntu:24.04 \
  bash -c "apt-get update && apt-get install -y curl && \
  curl -fsSL https://claude.ai/install.sh | bash && \
  claude"

For repeated use, build a custom Dockerfile so you don't reinstall on every run:

FROM ubuntu:24.04

RUN apt-get update && apt-get install -y curl git && \
    curl -fsSL https://claude.ai/install.sh | bash && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

WORKDIR /workspace
ENTRYPOINT ["claude"]

docker build -t claude-code .
docker run -it --rm \
  -v "$(pwd):/workspace" \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  claude-code

Method 4: VS Code Dev Containers

Dev Containers run your development environment inside a Docker container while keeping the VS Code UI on your Windows host. You get Linux compatibility, reproducible environments, and IDE integration in one package.

Setup

1. Install VS Code and the Dev Containers extension
2. Install Docker Desktop for Windows
3. Add a .devcontainer/devcontainer.json to your project

{
  "name": "Claude Code Dev",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "22"
    },
    "ghcr.io/devcontainers/features/git:1": {}
  },
  "postCreateCommand": "curl -fsSL https://claude.ai/install.sh | bash",
  "containerEnv": {
    "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}"
  },
  "remoteUser": "vscode"
}

Open the project in VS Code, then run Dev Containers: Reopen in Container from the command palette (Ctrl+Shift+P). VS Code rebuilds the container, installs Claude Code, and opens an integrated terminal where claude is available.

Set your ANTHROPIC_API_KEY as a Windows environment variable so it gets passed into the container automatically. In PowerShell: [System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-ant-...', 'User')

Installation Method Comparison

Each method trades off between setup complexity and compatibility. Here is how they compare:

Configuration

API Key Setup

Claude Code needs authentication. On first run, it opens your browser for OAuth. For headless or automated environments, set the API key directly:

# In WSL2 / Linux (add to ~/.bashrc or ~/.zshrc)
export ANTHROPIC_API_KEY=sk-ant-...

# In PowerShell (persistent, user-level)
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-ant-...', 'User')

# In PowerShell (current session only)
$env:ANTHROPIC_API_KEY = "sk-ant-..."

Windows Terminal Setup

Windows Terminal renders Claude Code's output correctly: 24-bit color, Unicode, proper line wrapping. Install it from the Microsoft Store or via winget:

winget install Microsoft.WindowsTerminal

Set your WSL2 distribution as the default profile in Windows Terminal settings for the smoothest workflow.

Git Configuration

Configure Git before using Claude Code. This is especially important on Windows to avoid line ending issues:

# Set your identity
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

# Fix line endings (critical on Windows)
git config --global core.autocrlf input

# Set default branch name
git config --global init.defaultBranch main

CLAUDE.md

After Claude Code is installed, run /init inside any project to generate a CLAUDE.md file. This gives Claude persistent context about your codebase: build commands, conventions, architecture. It is the most impactful post-install step. See our CLAUDE.md guide for detailed examples.

Common Issues

Node.js version mismatch (npm method only)

The npm package requires Node.js 18+. A common mistake on WSL2: having Node.js installed on Windows but not inside the WSL2 environment. Check from your WSL2 terminal:

node --version
# If not found or below v18, install via nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 22

Permission errors with npm

Never use sudo npm install -g. It creates root-owned files that break future npm operations. Use nvm instead, which installs Node.js in your home directory and avoids permission issues entirely.

CRLF vs LF line endings

Windows uses CRLF (\r\n), Linux uses LF (\n). When Claude Code edits files, it writes LF. If your repository has CRLF, you get spurious diffs. Fix it globally:

# Global Git config
git config --global core.autocrlf input

# Per-project .gitattributes (add to repo root)
# * text=auto eol=lf

# Fix existing files in a repo
git rm -r --cached .
git add .
git commit -m "Normalize line endings to LF"

WSL2 networking issues

If Claude Code can't reach the Anthropic API from WSL2, check your DNS resolution:

# Test connectivity
curl -I https://api.anthropic.com

# If DNS fails, override the resolver:
sudo bash -c 'echo "[network]" > /etc/wsl.conf'
sudo bash -c 'echo "generateResolvConf = false" >> /etc/wsl.conf'
sudo bash -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'

# Restart WSL2 from PowerShell:
# wsl --shutdown

claude: command not found

Open a new terminal window after installation. If it still doesn't work, check that the install location is in your PATH:

# In WSL2/bash
which claude
echo $PATH

# In PowerShell
Get-Command claude
$env:PATH -split ';'

Performance Tips

Use the Linux filesystem in WSL2

This is the single biggest performance improvement. Projects stored at /mnt/c/ (Windows drives accessed from WSL2) are 3-5x slower for file operations than projects stored in the native Linux filesystem at ~/.

# Create your projects directory in the Linux filesystem
mkdir -p ~/projects

# Clone directly into the Linux filesystem
cd ~/projects
git clone https://github.com/your-org/your-repo.git

# Access from Windows Explorer if needed:
# \\wsl$\Ubuntu\home\youruser\projects

Configure .wslconfig for memory

WSL2 defaults to using up to 50% of your system RAM. For large codebases, you may want to allocate more. Create or edit %USERPROFILE%\.wslconfig on the Windows side:

[wsl2]
memory=8GB
processors=4
swap=4GB

After editing, restart WSL2 from PowerShell: wsl --shutdown, then reopen your terminal.

Windows Terminal rendering

Enable GPU-accelerated rendering in Windows Terminal for smoother output when Claude Code streams long responses. In Windows Terminal settings, go to Rendering and enable "Use the new text renderer."

Frequently Asked Questions

Can I install Claude Code on Windows?

Yes. Four methods: WSL2 (recommended), native PowerShell installer, Docker, or VS Code Dev Containers. WSL2 gives full Linux compatibility. The native installer works for basic usage with some limitations around file watching and MCP servers.

Is WSL2 required for Claude Code on Windows?

No, but it is the recommended approach. The native PowerShell installer (irm https://claude.ai/install.ps1 | iex) works without WSL2. Docker Desktop is another WSL2-free option if you use the HyperV backend.

Why are file operations slow in WSL2?

Accessing Windows drives from WSL2 (via /mnt/c/) crosses a filesystem boundary. Every stat(), read(), and write() call goes through a translation layer. Store projects in the native Linux filesystem (~/projects/) for 3-5x faster performance.

Do I need Node.js to run Claude Code on Windows?

Not for the native installer or Docker methods. Node.js 18+ is only required if you use the npm installation: npm install -g @anthropic-ai/claude-code.

How do I fix CRLF line ending issues?

Run git config --global core.autocrlf input to convert CRLF to LF on commit. Add a .gitattributes file with * text=auto eol=lf to your repository for project-wide enforcement.

Related Guides