Claude Code on Windows: The Working Setup Guide

The Windows situation in 2026

Claude Code does not run natively on Windows. Anthropic ships official builds for macOS and Linux. Windows users run Claude Code through Windows Subsystem for Linux (WSL), which works well once configured correctly but has a handful of setup traps that catch new users.

This guide covers the working Windows setup for Claude Code in 2026: installing WSL, getting Claude Code running inside it, the file-system path quirks that break naive setups, and the workflow that keeps Windows users as productive as macOS users. If you want the cross-platform setup overview, our Claude Code setup guide covers it.

Step 1: Install WSL 2

WSL 2 is the version Claude Code requires. Older WSL 1 installations work but are slower and have more file-system edge cases. Open PowerShell as administrator and run:

wsl --install

This installs WSL 2 with Ubuntu by default. Reboot when prompted. After reboot, Ubuntu launches and asks for a username and password. Pick anything; this is local-only.

Verify the install:

wsl --version

You should see WSL version 2.x. If you see version 1.x, upgrade:

wsl --set-default-version 2
wsl --set-version Ubuntu 2

Step 2: Install Node.js inside WSL

Claude Code is an npm package, so you need Node.js inside WSL. Use nvm (Node Version Manager) for clean version handling:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20

Verify:

node --version
# Should show v20.x.x

Pin the version so updates do not break Claude Code:

nvm alias default 20

Step 3: Install Claude Code

Inside the WSL Ubuntu terminal:

npm install -g @anthropic-ai/claude-code

Then run:

claude

The first run authenticates you. It opens a browser link in your default Windows browser (this works because WSL forwards browser requests to Windows). Sign in with your Anthropic account, and the auth token persists locally.

The path trap that catches everyone

This is where most Windows setups break. WSL has two file systems: the Linux file system (fast, where you should keep your code) and the Windows file system (mounted at /mnt/c/, slow when accessed from WSL).

Wrong: Cloning your repo to /mnt/c/Users/you/projects/myapp/ and running Claude Code there. File operations are 10-50x slower because every read crosses the Windows-to-WSL boundary. Claude Code feels broken.

Right: Cloning your repo to ~/projects/myapp/ (which lives on the WSL ext4 file system). Everything is fast.

If you absolutely need the project to live on the Windows side (because IDE access requires it), use the Windows-side IDE through WSL's Remote-WSL extension rather than crossing file-system boundaries.

Step 4: Configure your editor

Three workable editor setups for Windows + WSL + Claude Code:

VS Code with Remote-WSL. Install VS Code on Windows. Install the "Remote - WSL" extension. Open your project in WSL by typing code . from the WSL terminal. The editor runs on Windows but treats the WSL file system as native. Claude Code in the WSL terminal edits the same files VS Code is showing.

JetBrains IDEs. WebStorm, IntelliJ, etc. support WSL projects. Open the project from \\wsl$\Ubuntu\home\you\projects\myapp\. Claude Code in the WSL terminal stays in sync. Slightly slower than Remote-WSL but works.

Terminal-only (no GUI editor). vim, helix, neovim inside WSL. Pure terminal workflow. Some developers prefer this; Windows + WSL handles it cleanly with a terminal like Windows Terminal or Wezterm.

The wrong setup: editing files in a Windows-native editor while Claude Code edits in WSL. Race conditions on saves, encoding mismatches on line endings. Pick one side of the fence and stay there.

Line-ending normalisation

Windows defaults to CRLF line endings; Linux uses LF. Claude Code generates files with LF (because it runs in Linux/WSL). If your repo has been edited from Windows tooling that converts to CRLF, you can end up with mixed-line-ending files that look noisy in git diffs.

Fix once, with a .gitattributes file at your project root:

* text=auto eol=lf
*.{cmd,bat,ps1} text eol=crlf

This forces LF on everything except Windows-specific scripts. Claude Code's output stays consistent with the rest of your codebase.

Step 5: Verify Claude Code is working

Inside WSL, navigate to a project directory and run:

cd ~/projects/myapp
claude

You should see Claude Code's interactive prompt. Try a low-stakes test:

> Read the package.json and tell me what scripts are defined

If this returns a useful answer, Claude Code is working. If it errors out, check three things:

1. WSL version: wsl --version (must be 2.x)
2. Node version: node --version (must be 18+)
3. File system: are you running Claude Code on a project living in ~/ rather than /mnt/c/?

The CLAUDE.md for Windows + WSL projects

Add a Windows-specific section to your CLAUDE.md if multiple developers on the project use different OSs:

## Cross-platform notes

This project is developed on macOS, Linux, and Windows (via WSL).

- Path separators: always use forward slashes in code, not backslashes
- Line endings: LF (enforced by .gitattributes)
- Shell scripts use bash, not PowerShell
- Windows-specific scripts (.cmd, .ps1) live in /scripts/windows/

This documents conventions Claude Code follows in every session, regardless of which contributor's machine it runs on.

Common Windows-specific issues

Five issues that catch Windows users specifically:

"npm: command not found" after WSL restart. nvm is shell-scoped; if your .bashrc is misconfigured, Node isn't on the PATH. Fix: re-run the nvm install line and verify the .bashrc block was added.

File watch limit exceeded. WSL inherits Linux's inotify limits which are too low for some projects. Fix: echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf then reboot WSL.

Slow file operations. Almost always means your project lives on /mnt/c/. Move it to ~/.

Browser-based auth doesn't open. WSL's browser forwarding requires wslu (sudo apt install wslu). Re-run claude after install.

Git credentials prompt every push. Configure Git to use the Windows credential manager: git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe".

Performance tips for Windows users

Three settings that materially improve Claude Code performance on Windows:

Allocate enough RAM to WSL. Create ~/.wslconfig on Windows (not in WSL):

[wsl2]
memory=8GB
processors=4

Default is 50% of host RAM and all CPUs, which is sometimes too constrained on shared machines. Restart WSL after changes (wsl --shutdown).

Use Windows Terminal, not the legacy console. Windows Terminal handles colour, copy-paste, and tab management better. Get it from the Microsoft Store.

Keep Docker Desktop integration enabled. If you use Docker, the WSL 2 backend in Docker Desktop integrates seamlessly. Docker commands inside WSL just work.

What changes about the workflow

Five workflow notes specific to Windows + Claude Code:

Sessions live in WSL terminals. Open a Windows Terminal tab pointing at your WSL distro. Run Claude Code there. Stay there for the session.

Memory and skills are cross-platform. memory.md, skills, and hooks work identically on Windows-via-WSL as on macOS or Linux. No Windows-specific configuration is needed.

Cowork mode works. Claude Code's Cowork feature (always-on assistance) works in WSL terminals, with the same usage profile as on other OSs.

Git via WSL. Use Git from the WSL side, not Windows-side. Avoids the line-ending and credential issues that plague mixed setups.

npx create-claudify works inside WSL. The Claudify install flow is identical to other OSs.

The configuration shortcut

Setting up Claude Code on Windows is real work. Once it works, the configuration patterns that make Claude Code productive (memory architecture, skill libraries, audit hooks) are platform-independent.

Claudify ships these patterns pre-configured. Run npx create-claudify from inside WSL and you inherit a working operating system without spending the first week building configuration.

Quick reference

You need...	Command
Install WSL 2	wsl --install (PowerShell as admin)
Install Node.js	nvm install 20 (inside WSL)
Install Claude Code	npm install -g @anthropic-ai/claude-code
Run Claude Code	claude in any project directory inside WSL
Project location	~/projects/ not /mnt/c/
Editor	VS Code + Remote-WSL extension

Next steps

Once Claude Code is running cleanly on Windows + WSL, the workflow is identical to macOS or Linux. The platform difference disappears after the install.

Get Claudify. The Claude Code operating system that runs identically across macOS, Linux, and Windows-via-WSL. Skills, memory, agents, and audit hooks ship out of the box.