Claude Code on Windows: install, setup and common fixes

Claude Code runs natively on Windows 10 (1809 or later) and Windows 11. Open PowerShell and run irm https://claude.ai/install.ps1 | iex; no admin rights and no Node.js needed. Install Git for Windows too, so the agent gets a Bash shell next to PowerShell. If you want Claude Code’s sandbox, run it inside WSL2 instead: native Windows has none.

irm https://claude.ai/install.ps1 | iex

Open a new terminal, check it, and start it in your project:

claude --version
cd C:\code\my-app
claude

Your browser opens to sign in. Claude Code needs a Pro, Max, Ultra, Team or Enterprise plan, or an Anthropic Console account; the free plan doesn’t include it.

Which install method should I use on Windows?

All of them install the same native binary. npm still works: it pulls the same binary in through an optional dependency, and the installed claude doesn’t use Node at runtime. Pick one method and don’t mix them.

The PowerShell and CMD installers put claude.exe in %USERPROFILE%\.local\bin. To get the stable channel, about a week behind and without releases that had major regressions:

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable

'irm' is not recognized means you’re in CMD, not PowerShell. The token '&&' is not a valid statement separator means the opposite. A parameter cannot be found that matches parameter name 'fsSL' means you pasted the macOS/Linux command into PowerShell. Your prompt starts with PS in PowerShell.

With WinGet, Claude Code can run the upgrade for you if you set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1. The upgrade may fail while Claude Code is running, because Windows locks the executable; Claude Code then shows you the command to run by hand.

Do I need Git Bash for Claude Code on Windows?

No, but you probably want it. Claude Code picks its shell from what it finds:

The model knows Bash commands by heart. Without Git Bash it has to translate everything into PowerShell, and scripts written for Bash won’t run. Install it with winget install --id Git.Git, or from git-scm.com with “Add to PATH” selected.

If Claude Code can’t find Git Bash, point it at the file in %USERPROFILE%\.claude\settings.json:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

The file must be bash.exe or sh.exe. Point it at git-bash.exe, the launcher, and Claude Code ignores the setting without an error. Run where.exe git to find your installation.

The PowerShell tool is on by default for Claude subscriptions and Console accounts, even with Git Bash installed. For Amazon Bedrock, Google Cloud and Microsoft Foundry, turn it on with "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1" in the same env block; "0" turns it off. It prefers PowerShell 7 (pwsh.exe) and falls back to Windows PowerShell 5.1. It starts PowerShell with -ExecutionPolicy Bypass for its own process only, so your machine’s policy stays as it is. It doesn’t load your PowerShell profile.

In the PowerShell tool, a grep or rg that finds nothing, a git diff that finds changes, or a robocopy that copied files can show Error: Exit code 1, which looks like a failure. Nothing failed. Those tools use exit codes to report results.

Should I run Claude Code in WSL instead?

WSL 1 runs Claude Code too, but without the sandbox.

In WSL 2, install the two packages the sandbox needs, restart Claude Code, then turn it on with /sandbox:

sudo apt-get install bubblewrap socat

Keep the project in the Linux file system (~/code/my-app), not under /mnt/c: Microsoft’s own WSL guidance is to store files on the side of the tools that use them.

The failIfUnavailable trap: "sandbox": { "failIfUnavailable": true } is a good setting on macOS and Linux. Copy it into a settings file that native Windows also reads, and Claude Code refuses to start there, because the sandbox doesn’t exist on native Windows.

What about the Claude desktop app?

The Claude desktop app has Claude Code built in, in the Code tab. You don’t need Node.js or the CLI for it. Download the Windows installer from claude.com/download; there’s an ARM64 build too. It needs a Pro, Max, Ultra, Team or Enterprise plan.

In a new session, the environment picker offers Local, Cloud, SSH and, on Windows, WSL, which runs the session inside a WSL 2 distribution with Linux paths. The app reads the same settings files as the CLI.

Older versions of the desktop app register a Claude.exe in WindowsApps that wins on PATH, so typing claude opens the app instead of the CLI. Update the desktop app.

Where are Claude Code’s settings on Windows?

Set CLAUDE_CONFIG_DIR to keep the home-folder files somewhere else. Run /status inside Claude Code to see which files loaded, and claude doctor in your shell for install health and settings errors.

How do permissions behave differently on Windows?

Three things catch Windows users:

• “Yes, don’t ask again” saves next to the folder you started in. On macOS and Linux, Claude Code saves the rule at the repository root. On Windows it stays with .claude\settings.json in your starting folder. Start Claude Code in a subfolder once, and the rule seems to be gone the next time you start at the root. Always start at the root.
• Network paths always ask. A command that touches \\server\share prompts whatever your rules say, because the lookup can send your Windows credentials to that host. You can’t add a UNC share as a working directory either. Map it to a drive letter and pass it at start: claude --add-dir Z:\.
• A Bash deny rule switches the PowerShell tool off. With Git Bash installed, any Bash(...) deny rule, even Bash(git push *), silently turns off the PowerShell tool for the session. Otherwise Claude could run in PowerShell what you denied in Bash. Keep PowerShell on by adding a matching PowerShell rule:

{
  "permissions": {
    "deny": [
      "Bash(git push *)",
      "PowerShell(git push *)"
    ]
  }
}

PowerShell rules match aliases too, case-insensitively: PowerShell(Get-ChildItem *) also covers gci, ls and dir. In path rules, Windows paths are written in POSIX form: C:\Users\alice becomes /c/Users/alice, so Read(//c/**/.env) blocks .env files anywhere on C:.

Common problems and fixes

Fix PATH for your user, once:

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

Find duplicate installs and remove the extras:

where.exe claude
npm uninstall -g @anthropic-ai/claude-code
winget uninstall Anthropic.ClaudeCode
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"

The last line removes an old local npm install from earlier versions. Run only the lines for installs you actually have.

Restore claude.exe after a failed update:

Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe

Behind a corporate proxy, set both variables before installing:

$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

If Git Bash is installed and set correctly but Claude Code still can’t use it, endpoint security (AppLocker, Group Policy, EDR) may be blocking it. Ask IT to allow claude.exe and the processes it starts, including cmd.exe and bash.exe.

Uninstall

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

Your settings stay in %USERPROFILE%\.claude and %USERPROFILE%\.claude.json. Delete them only if you want your rules, MCP servers and history gone too. The VS Code extension and the desktop app recreate the folder if they’re still installed.

Contenox

Contenox, a Windows desktop app, can host Claude Code: on the Agents page, the “Claude Code” preset (it needs Node 22 or later) signs in with your Claude subscription or an Anthropic Console account. Your Contenox permission rules then govern Claude Code too, and on Windows a sandbox limits writes to the project folder. That covers the gap native Windows leaves, at least for writes; reads can’t be restricted on Windows. Download it.

Related guides

• AI coding agents on Windows: every major agent, native or WSL
• Codex on Windows: the same setup for Codex, which has a native Windows sandbox
• Why does my coding agent keep asking for permission?: rules that remove routine prompts
• How to sandbox AI coding agents: what to use when there’s no built-in sandbox