Using Claude Code on Windows — Native vs WSL2

Claude Code was originally designed for macOS and Linux, but native Windows support has been officially released. You can now run Claude Code directly from PowerShell or the Command Prompt — no WSL (Windows Subsystem for Linux) required.

At the same time, running Claude Code inside a WSL2 Ubuntu environment is still a fully supported and often preferable approach, depending on your project type.

Two paths are open to you:

• Option A: Native Windows installation (no WSL, quick setup)
• Option B: WSL2 + Ubuntu (for Linux-based workflows)

We'll also help you decide which approach fits your situation best.

Native Windows vs WSL2 — Which One Should You Choose?

Before diving into the setup steps, here's a quick comparison to help you decide.

Native Windows (Option A):

• Works directly in PowerShell or Windows Terminal
• No separate Node.js installation needed (bundled with the installer)
• Operates on your Windows filesystem natively
• Setup takes under 5 minutes

WSL2 (Option B):

• Gives you a full Bash/Zsh shell environment on Windows
• Linux toolchains (make, gcc, etc.) work out of the box
• Better suited for projects that depend on shell scripts or Makefiles
• Higher performance when your project files live inside the WSL2 filesystem

Bottom line: If you're primarily working on Windows-native projects, go with Option A. If your project requires a Linux environment or you're contributing to open-source software, Option B is the way to go.

Option A: Installing the Native Windows Version

Step 1 — Check the Prerequisites

• Windows 10 version 21H2 or later, or Windows 11
• PowerShell 5.1 or newer (Windows 11 includes this by default)
• An active internet connection

Step 2 — Run the Official Installer

Open PowerShell as Administrator and run the following command:

# Run the official installer (includes Node.js)
irm https://claude.ai/install.ps1 | iex

The script will automatically:

• Download the latest Claude Code binary
• Install it to ~\.local\bin
• Add the directory to your PATH

After the script finishes, open a new PowerShell window and verify the installation:

# Check installed version
claude --version
# Example output: claude 1.x.x

Step 3 — Sign In to Your Anthropic Account

# Sign in (opens your default browser automatically)
claude login

Log in to your Anthropic account in the browser that opens. Once authenticated, your terminal will display a success message.

Step 4 — Run Claude Code on a Project

# Navigate to your project directory
cd C:\Users\YourName\projects\my-app
 
# Launch Claude Code
claude
 
# Or run a task directly
claude "Explain the directory structure of this project"

That's all it takes to get started on Windows.

Option B: Installing via WSL2

Step 1 — Enable WSL2

Open PowerShell as Administrator and run:

# Install WSL2 (may require a restart)
wsl --install
 
# If already installed, check the version
wsl --version

After restarting, Ubuntu will launch automatically. Set up your Linux username and password when prompted.

Step 2 — Install Node.js Inside Ubuntu

Open a WSL2 Ubuntu terminal and run:

# Add the Node.js 22 LTS repository and install
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
 
# Verify the installation
node --version   # v22.x.x
npm --version    # 10.x.x

Step 3 — Install Claude Code via npm

# Install globally
npm install -g @anthropic-ai/claude-code
 
# Verify
claude --version

Step 4 — Sign In and Test

claude login

⚠️ Performance Tip: Keep Your Project Files in the WSL2 Filesystem

When working in WSL2, make sure your project files are stored inside the WSL2 filesystem (e.g., ~/projects/) rather than on the Windows drive.

Accessing Windows files via /mnt/c/Users/... goes through the 9P protocol, which significantly slows down file operations.

# Recommended: store your project inside WSL2's home directory
mkdir -p ~/projects/my-app
cd ~/projects/my-app
claude

Persisting Instructions with CLAUDE.md

Regardless of which installation method you use, placing a CLAUDE.md file in your project root lets you give Claude Code persistent, project-specific instructions.

# My Project
 
## Coding Style
- Use TypeScript (ES Modules syntax)
- Write comments in English
- Use try/catch for all error handling
 
## Prohibited
- No console.log in production code
- No use of the `any` type
 
## Common Commands
- `npm run dev` — start the development server
- `npm run build` — production build
- `npm test` — run tests

With this file in place, Claude Code remembers your project's rules across sessions. To learn how to use hooks for more advanced automation, check out the Claude Code Custom Hooks Complete Guide.

Common Errors and How to Fix Them

"'claude' is not recognized as a cmdlet or command"

Cause: The PATH variable doesn't include the Claude Code binary directory. Fix: Restart PowerShell. If the issue persists, manually add the path:

# Add to PATH for the current session
$env:PATH += ";$env:USERPROFILE\.local\bin"
 
# Persist the change across sessions
Add-Content $PROFILE "`n`$env:PATH += `";$env:USERPROFILE\.local\bin`""

"Permission denied when running npm install -g" (WSL2)

Cause: Global npm directory permissions issue. Fix: Use nvm to install Node.js in user space:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
 
# Install the LTS version of Node.js
nvm install --lts
nvm use --lts
 
# Then install Claude Code
npm install -g @anthropic-ai/claude-code

"Authentication fails / browser doesn't open"

Fix: Try claude login --no-browser. This prints a URL to the console that you can paste into your browser manually to complete authentication.

For more troubleshooting steps, see the Claude Code Setup Troubleshooting FAQ.

Integrating with VS Code

Claude Code works seamlessly in the VS Code integrated terminal. You can also install the official Claude Code extension for a tighter editor integration.

# Install from the command line
code --install-extension anthropic.claude-code

With the extension installed, you can:

• Highlight code in the editor and ask Claude about it directly
• Generate and edit code inline
• Manage files through the chat panel

For the full rundown, see the Claude Code VS Code Extension Productivity Guide.

Setting Up a Multi-Project Workflow

Once Claude Code is running, you'll quickly find that it works best when each project has its own CLAUDE.md. Here's a simple pattern that keeps things organized across multiple repositories:

# Create a workspace root (native Windows)
mkdir C:\dev\workspace
cd C:\dev\workspace
 
# Each project gets its own CLAUDE.md
mkdir project-a && cd project-a
New-Item CLAUDE.md

# Or in WSL2
mkdir -p ~/dev/workspace/project-a
cd ~/dev/workspace/project-a
touch CLAUDE.md

The key insight is that Claude Code reads CLAUDE.md from the current directory and all parent directories — so you can maintain a root-level CLAUDE.md with organization-wide rules and a project-level one for project-specific settings. This layered approach scales well as you manage more projects.

Summary

Two ways to run Claude Code on Windows, then:

• Option A (Native): The fastest path — use this for Windows-native projects.
• Option B (WSL2): The better fit when you need a Linux shell or toolchain.

Either way, setting up a CLAUDE.md file in your project root will make Claude Code significantly more effective by keeping your project rules and preferences persistent across sessions.

If you run into any issues getting started, the Claude Code Not Starting Checklist is a helpful next stop.

Pick the path that matches your project, install it once, and write your CLAUDE.md before the first real session.