DEV Community

aicoding-guide
aicoding-guide

Posted on Originally published at aicoding-guide.com

Claude Code on Windows, native or WSL, and what trips people up

#claudecode #windows #wsl #setup

Originally published at https://aicoding-guide.com.

Claude Code started out aimed at macOS and Linux, with Windows users pointed at WSL. There is now a native Windows build you can run straight from PowerShell. Which one to choose comes down to one question: do you need sandboxing?

This article compares the two, gives the install steps for each, and collects the things that actually trip people up.

Key point
What you will learn

  • Native versus WSL, and the sandboxing difference that decides it
  • Install steps for each, and whether Git for Windows matters
  • The gotchas: hooks, paths, encoding and line endings

Native versus WSL 2

Native Windows WSL 2
Runs on Windows directly Linux inside WSL (Ubuntu, etc.)
Requires Nothing; Git for Windows is optional WSL 2 enabled
Sandboxing Not supported Supported
Shell tool Git Bash when Git for Windows is installed, otherwise the PowerShell tool bash / zsh
Where projects live Windows drives (C:\...) Inside WSL (/home/...) is recommended
Linux tooling such as Docker Needs a Windows build Linux builds work as-is
Suits Windows-native development (.NET, Node) Linux toolchains, or sandboxed command execution

WSL 1 is the third option, for when WSL 2 is unavailable; like native Windows, it does not support sandboxing.

Touching Windows files from WSL is slow
Working on a project under /mnt/c/... from WSL makes file I/O dramatically slower. If you choose WSL, keep the project inside WSL, under ~/projects/ for example.

Installing the native build

1. Git for Windows (optional)

The documentation calls Git for Windows optional. With it, Git Bash backs the Bash tool; without it, Claude Code runs shell commands through the PowerShell tool. If your hooks and scripts assume bash, install it. The defaults from Git for Windows are fine.

With Git for Windows installed, the PowerShell tool is available alongside Bash: on by default for claude.ai and Console accounts, and enabled with CLAUDE_CODE_USE_POWERSHELL_TOOL=1 in Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry sessions. Set it to 0 to turn the tool off.

2. Install Claude Code

Open PowerShell and run:

irm https://claude.ai/install.ps1 | iex
Enter fullscreen mode Exit fullscreen mode

In CMD the command is different — your prompt shows PS C:\ in PowerShell and C:\ without the PS in CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Enter fullscreen mode Exit fullscreen mode

WinGet works too, but a WinGet install does not auto-update, so run winget upgrade Anthropic.ClaudeCode periodically:

winget install Anthropic.ClaudeCode
Enter fullscreen mode Exit fullscreen mode

The npm package is another option and needs Node.js 22 or later. You do not need to run the installer as Administrator.

3. Start it and check 

cd C:\path\to\project
claude
Enter fullscreen mode Exit fullscreen mode

The first run prompts you to log in. claude doctor reports installation health and settings-file validation errors without starting a session.

If Claude Code cannot find Git Bash, point at it in your settings file:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}
Enter fullscreen mode Exit fullscreen mode

Installing in WSL

Sandboxed command execution requires WSL 2; WSL 1 does not support it.

  1. Run wsl --install in an elevated PowerShell and restart. Ubuntu is installed by default.
  2. Open the Ubuntu terminal and install Node.js if you plan to use the npm package (nvm is the easy route).
  3. Install with the Linux command — you run it inside the WSL terminal, not from PowerShell or CMD: 
curl -fsSL https://claude.ai/install.sh | bash
Enter fullscreen mode Exit fullscreen mode

For VS Code, install the WSL extension, open a folder inside WSL, and install the Claude Code extension into WSL.

What trips people up

Hooks and scripts run through Git Bash

With Git for Windows installed, the Bash tool uses Git Bash, so PowerShell cmdlets are not available directly. Invoke PowerShell explicitly instead:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "powershell -NoProfile -File .claude/hooks/format.ps1"
          }
        ]
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

For hook basics, see Run lint and format on save with Claude Code hooks.

Writing paths

In permission patterns and CLAUDE.md, forward slashes (src/**) work on Windows too. Avoid backslashes, which need escaping inside JSON.

Encoding

If command output comes back garbled, set PowerShell's output encoding to UTF-8:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
Enter fullscreen mode Exit fullscreen mode

Line endings

A CLAUDE.md or hook script saved with CRLF by a Windows editor can fail under Git Bash when a stray \r ends up in the script. Set *.sh text eol=lf in .gitattributes and save scripts with LF.

Summary

  • Install natively from PowerShell with irm https://claude.ai/install.ps1 | iex; Git for Windows is optional, and without it the PowerShell tool runs commands
  • Sandboxing means WSL 2. Native Windows and WSL 1 do not support it. Keep projects inside WSL when you go that route
  • Write hooks and scripts for Git Bash, and keep line endings at LF
  • Fix garbled output with UTF-8 output encoding, and use forward slashes in paths

Top comments (0)