Claude Code on Windows: Native Setup Without WSL

Key takeaways

• Claude Code runs natively on Windows without WSL, using Git Bash as its shell layer.
• The two hard prerequisites are Git for Windows and Node.js 18 or newer.
• The most common failure is npm's global bin directory missing from PATH; add %APPDATA%\npm and restart the terminal.
• Choose WSL2 when your CI, Docker setup, or scripts assume a Linux environment; otherwise the native install is the lower-maintenance path.
• Pricing and token consumption are identical across platforms; only workflow overhead differs.

Yes, Claude Code on Windows runs natively, without WSL, and setup takes about ten minutes once you know the two real prerequisites: Git Bash and a current Node.js install. Most guides still tell you to reach for WSL first, which adds a layer you probably don't need. This guide covers one tested native install path and the fixes for the errors that actually break it.

Does Claude Code work on Windows natively?

Yes. Claude Code runs natively on Windows without WSL, using Git Bash for its shell layer. Anthropic's setup documentation lists native Windows support alongside the WSL option, so you can pick based on your workflow rather than a hard requirement.

The change matters if you run parallel agents across repos. Native execution means your agents and your Linear-driven queue live in the same environment as the rest of your tooling, no WSL filesystem translation, no path mapping surprises when agents review the diff or hand off between worktrees.

The trade-off: native Windows still depends on Git Bash being installed and on PATH, which is where most first-run failures happen. We cover those in the troubleshooting section below. For the full set of setup guides, see our guides library.

What are the system requirements to run Claude Code on Windows?

Native Windows support needs Windows 10 or later, a recent Node.js install (Node 18+ is the safe floor), Git for Windows, and at least 8 GB of RAM so you can run more than one agent comfortably. You also need a paid Claude account or API key with usage credits.

Requirement	Minimum	Practical for parallel agents
OS	Windows 10	Windows 11
Node.js	18	Current LTS
Git	Git for Windows	Git Bash included, worktrees enabled
RAM	8 GB	16 GB+
Account	Claude Pro or API key	Team plan with a shared credit pool

If you plan to run several agents at once, budget for credits accordingly: polling and queued prompts burn tokens faster than a single interactive session, and the math changes per seat (what a coding agent really costs).

How do you install Claude Code on Windows step by step?

Native Windows install takes about ten minutes: install Git and Node, run one npm command, verify PATH, then log in from a terminal.

Install prerequisites

Install Git for Windows first, since Claude Code's shell tooling depends on Git Bash even in a native setup. Then install Node.js 18 or newer from the official installer; the LTS build is fine. Anthropic's Claude Code documentation lists these as the baseline requirements. Skip WSL for now, because you do not need it for the native path.

Run the installer

Open a fresh PowerShell or Command Prompt window and run:

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

If npm throws a permissions error, close the terminal and reopen it as administrator, or use a Node version manager so the global prefix points at your user directory.

Verify the install

Run claude --version. If you get a version number, you are done. If you get "command not found," npm's global bin directory is missing from PATH — add %APPDATA%\npm to your user PATH, restart the terminal, and test again. This is the single most common failure point on Windows.

Authenticate and first run

Run claude inside a project directory. The first launch opens a browser window for OAuth login; approve it and the terminal drops you into an interactive session. From here the workflow matches macOS and Linux: point it at a repo, review the diff, and queue the next prompt. If you are weighing Claude Code against other hosted agents before committing your team's workflow, see this comparison of cloud coding agents.

Do you still need WSL to run Claude Code on Windows?

For most day-to-day work, no. Native Windows handles the CLI, file editing, and git fine, and if your team queues prompts and reviews diffs through a tool like Aerunit (structuring prompts for coding agents), the shell underneath matters less than whether agents stay busy.

WSL2 still earns its keep in three cases. First, if your scripts lean on Linux-only tooling: make, jq, grep pipelines, or POSIX shell syntax that breaks in PowerShell. Second, if you run multiple agents on git worktrees and want worktree behavior identical to your Linux CI, so an agent passing locally does not fail in the pipeline. Third, if your team develops against Linux production targets and you want parity between what agents produce and what ships.

The honest tradeoff: WSL2 adds setup friction, occasional file-watching weirdness across the /mnt boundary, and a second environment to keep updated. If you are not hitting Linux-specific failures, native Windows plus a good workflow layer is the lower-maintenance path.

What are the most common Claude Code Windows errors and fixes?

Native Windows support shipped with a documented install path in the Anthropic docs, but most failures cluster into three buckets.

Command not found after install

If claude returns "command not found," the npm global bin directory is not on your PATH. Run npm config get prefix, append the returned bin folder to your user PATH via System Properties, then restart your terminal. A Git Bash window that was open during install will not pick up the change; close and reopen it. PowerShell users should verify with Get-Command claude.

Git and shell errors

Claude Code on Windows requires Git for Windows, because it relies on Git Bash for shell execution. If you see "shell not found" or git-related spawn errors, reinstall Git for Windows and confirm git --version works from the same terminal you run claude in. Node version mismatches also surface here: use an LTS release, since older Node builds fail on native module loading.

Permission and policy errors

PowerShell's default execution policy blocks npm-installed launchers. Run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned if you hit "running scripts is disabled." For network errors behind a corporate proxy, export HTTPS_PROXY before launching. If an agent keeps failing on a step and you cannot tell why, log the failing prompt and handoff context in your queue rather than re-pasting it; we write more about structuring agent handoffs on the Aerunit blog.

How does Claude Code on Windows differ from macOS or Linux setups?

Native Windows runs Claude Code in PowerShell or cmd, so shell-based hooks, Bash snippets in slash commands, and MCP servers launched with Unix-style commands need adjusting. Anything calling grep, sed, or && breaks unless you point it at Git Bash or rewrite it. Git worktrees, the backbone of running parallel agents across repos, work the same, but your terminal multiplexer and scripts may not.

The bigger gap is workflow tooling. Most orchestration layers for agent fleets assume a Unix shell and a POSIX path layout, and multi-agent setups on Windows hit that assumption first: queue scripts, diff reviewers, and MCP servers that spawn subprocesses. If you keep hitting those walls, WSL2 gives you a full Linux environment with GPU support and near-native file performance, which is Microsoft's own recommended path for Linux-first toolchains (Microsoft WSL2 docs). Your Linear-to-agent pipeline, including Aerunit, behaves identically there because it sees a standard Linux box.

In practice, the difference shows up in small places rather than big ones. A hook that pipes a diff through grep and awk works on a Mac and fails on native Windows until you route it through Git Bash explicitly. A launch script that assumes /usr/bin/env needs a Windows equivalent or a wrapper. An MCP server configured with a POSIX-style path in claude_desktop_config.json needs the Windows path format instead. None of these are blockers, and each takes minutes to fix once you know the pattern: find the Unix assumption, decide whether to rewrite it for PowerShell or point it at Git Bash, and test it from the same terminal you launch Claude Code from. Teams that document these fixes in a shared setup script stop hitting them entirely, because every new machine gets the same corrected configuration on day one.

When should Windows users choose WSL over native Claude Code?

Use WSL when your stack already assumes Linux: your CI runs in a Linux container, your Docker Compose setup expects Linux paths, or your scripts use shell utilities that break on Windows. Native Claude Code works fine for plain TypeScript or Python repos, but parity with a Linux build pipeline is the deciding factor.

The second reason is agent orchestration. If you run parallel agents across git worktrees and queue the next prompt through a tool like Aerunit, Conductor, or Agentastic, WSL gives you a filesystem and shell environment those workflows were built around. Fewer path-format surprises when an agent reviews the diff or hands work to a subagent.

Stay native if your team is on Windows-only tooling, your CI matches Windows, or you have never touched WSL and the repo is simple. The native install is one command; adding WSL just to run it is overhead you do not need.

FAQ

Can I run multiple Claude Code sessions in parallel on one Windows machine?

Yes. Native Windows runs each session as its own process, and git worktrees let parallel agents work separate copies of a repo without conflicts. Budget for it, though: 16 GB of RAM is the practical floor for several agents, and queued prompts burn API credits faster than one interactive session. The shell underneath stays Git Bash per session.

Does Claude Code on Windows cost extra or use more tokens than on Mac?

No. Pricing and token consumption are identical across platforms because the model usage is the same. What differs is workflow overhead: if your Windows setup pushes you toward workarounds that re-paste context or retry failed steps, you waste tokens. A clean native install, or WSL2 if your stack needs it, keeps costs in line with a Mac setup.

How do I update Claude Code on Windows after installing it?

Run the same npm command you used to install: npm install -g @anthropic-ai/claude-code, which pulls the latest version over the existing one. Then verify with claude --version. If the update reports an old number, check that npm's global bin directory is still on PATH and restart your terminal before testing again.

Will Claude Code work with PowerShell or does it need Git Bash?

Both, in different roles. You launch and run Claude Code from PowerShell or cmd, but the shell tooling underneath depends on Git Bash, which is why Git for Windows is a hard prerequisite. Anything in your hooks or scripts calling grep, sed, or && must point at Git Bash or be rewritten for PowerShell.