Claude Code — Windows Installation & Setup Guide

A bulletproof, step-by-step guide for installing Claude Code on domain-joined Windows workstations, including the PATH fix the native installer leaves as a manual step.

1. Overview

Claude Code is Anthropic’s terminal-based AI coding agent. It reads code, edits files, and runs commands directly from the command line. This guide covers the native Windows installer and, critically, the PATH remediation step the installer does not complete on its own.

Why this guide exists

The native installer (irm https://claude.ai/install.ps1 | iex) places the Claude Code binary at:

C:\Users\<username>\.local\bin\claude.exe

On many machines — especially domain-joined workstations where the Windows user profile contains a dot (for example james.ACMELABS) — the installer does not append this folder to the user PATH. The installer reports success, but the claude command fails with:

claude : The term 'claude' is not recognized as the name of a cmdlet, function,
script file, or operable program.

This is a known issue tracked upstream as GitHub issue #21365. The fix is trivial once you know it, but undiscoverable without guidance.

What this guide assumes: You have local admin rights on the workstation, a Claude Pro, Max, Team, Enterprise, or Console account for authentication, and internet access to claude.ai, github.com, and git-scm.com.

What you will install

2. Pre-Install Checklist

Work through every item in this section before running the installer. Skipping any of them is the most common cause of a broken install.

Verify Windows version

1. Press Win + R, type winver, press Enter.
2. Confirm you are on Windows 10 version 1809 or later, or Windows 11 (any version).

Install Git for Windows

This step is mandatory. Claude Code shells out to Git Bash internally for command execution even when launched from PowerShell. Without Git Bash, Claude Code will fail at runtime with non-obvious errors.

1. Go to https://git-scm.com/downloads/win and download the 64-bit Git for Windows installer.
2. Run the installer. Accept all default options. Do NOT change them unless you know exactly why.
3. Critically, on the “Adjusting your PATH environment” screen, confirm the middle option (Git from the command line and also from 3rd-party software) is selected. This is the default.
4. Finish the installer.
5. Close any open PowerShell windows, then open a fresh PowerShell window and verify:

git --version

You should see a version string like git version 2.45.x.windows.1. If you get 'git' is not recognized, the PATH option was not selected during install. Re-run the Git installer and choose the middle PATH option.

⚠ Do not skip this step. A Claude Code install without Git Bash appears to succeed. It will fail silently the first time Claude tries to run a shell command. Catch this now, not three days into usage.

Confirm PowerShell execution policy

The installer is a PowerShell script fetched over HTTPS. Your execution policy must permit it to run. Check current policy:

Get-ExecutionPolicy -Scope CurrentUser

Acceptable values are RemoteSigned, Unrestricted, or Bypass. If you see Restricted or AllSigned, set it to RemoteSigned for your current user only:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Accept the prompt. This only affects your user profile, not the machine.

Have your Claude account ready

You will authenticate after install via a browser prompt. Before you start, make sure you can sign in to one of the following at claude.ai:

• Claude Pro ($20/month) — sufficient for most engineering work
• Claude Max ($100–$200/month) — higher rate limits
• Claude Team or Enterprise — for organizations
• Anthropic Console account with API credits — for API-based billing

⚠ Free Claude.ai accounts will not work. The free Claude.ai tier does not include Claude Code. If you try to authenticate with a free account, the CLI will refuse.

3. Install Claude Code

With Git for Windows installed and a Claude account in hand, you are ready to run the native installer.

3.1 Run the installer

1. Open a fresh PowerShell window as your regular user. Do NOT run as Administrator.
2. Confirm you are in PowerShell, not CMD. Your prompt should begin with PS, like PS C:\Users\yourname>. If it begins with C:\ without PS, you are in CMD — close it and open PowerShell.
3. Run the one-line installer:

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

The installer will download the binary and print output similar to:

Setting up Claude Code...
Claude Code successfully installed!
  Version: 2.1.114
  Location: C:\Users\<username>\.local\bin\claude.exe
  Next: Run claude --help to get started

Setup notes:
  - Native installation exists but C:\Users\<username>\.local\bin is not in
    your PATH. Add it by opening: System Properties ...

If you do NOT see the “Setup notes” section: Your PATH already includes ~/.local/bin (rare on fresh Windows installs, common on developer machines). Skip Section 4 and proceed to Section 5 to verify.

4. Fix the PATH

This is the step the installer does not complete. If you saw the “Setup notes” warning in Section 3, do this now. This procedure uses PowerShell rather than the Windows GUI because it is deterministic, repeatable, and does not depend on the user clicking through the correct sequence of dialogs.

Add ~/.local/bin to your user PATH

In the same PowerShell window (or a new one — it does not matter), run this exact command:

$claudeBin = Join-Path $env:USERPROFILE ".local\bin"
$currentPath = [Environment]::GetEnvironmentVariable("PATH", "User")
if ($currentPath -notlike "*$claudeBin*") {
    [Environment]::SetEnvironmentVariable("PATH", "$currentPath;$claudeBin", "User")
    Write-Host "Added $claudeBin to user PATH" -ForegroundColor Green
} else {
    Write-Host "$claudeBin is already in user PATH" -ForegroundColor Yellow
}

This does three things safely:

• Reads your CURRENT user PATH (not the merged system+user PATH). This prevents the common mistake of overwriting the user PATH with the combined value.
• Checks whether the folder is already listed, so you can run this twice without creating a duplicate.
• Writes the updated value to the user scope, which persists across reboots and does not require admin rights.

Restart your terminal

⚠ The current PowerShell window will NOT see the change. PowerShell caches environment variables when the session starts. You must close this window and open a fresh one for PATH changes to take effect. This is Windows behavior, not a bug.

1. Close every open PowerShell, CMD, VS Code integrated terminal, and Git Bash window.
2. Open a new PowerShell window.
3. Verify the PATH now contains your .local\bin folder:

$env:PATH -split ";" | Select-String ".local"

You should see one line pointing to your profile’s .local\bin folder. If nothing prints, something went wrong — re-run the command above in this section.

5. Verify and Authenticate

Confirm claude is on PATH

In a fresh PowerShell window, run:

claude --version

You should see a version string like 2.1.114. If you get 'claude' is not recognized, go back to Section 4 — your PATH update did not take, or you are in a terminal that was opened before the update.

Run claude doctor

Before authenticating, run the built-in diagnostic. It catches common setup issues before you hit them during real work:

claude doctor

You will see a structured report with two sections, Diagnostics and Updates. A healthy install looks like this:

Diagnostics
├ Currently running: native (2.1.114)
├ Path: C:\Users\<username>\.local\bin\claude.exe
├ Config install method: native
└ Search: OK (bundled)
Updates
├ Auto-updates: enabled
├ Auto-update channel: latest
├ Stable version: 2.1.98
└ Latest version: 2.1.114

5.3 Set up your working folder

Before you launch Claude Code for the first time, set up a standard working folder at C:\repo. This keeps every AcmeLabs repo in one short, predictable path.

Why C:\repo:

• Avoids Windows’ 260-character path limit that deep profile folders can trigger
• Sits outside OneDrive sync, which corrupts .git files
• No dots or spaces in the path (unlike C:\Users\patrick.ACMELABS\...)
• Short enough to type dozens of times a day without thinking

One-time setup in PowerShell (no admin needed):

mkdir C:\repo

Navigate to it:

cd C:\repo

Or from anywhere on the C: drive:

cd \repo

Use Tab completion for subfolders — type cd \repo\a then press Tab and PowerShell fills in the rest.

✓ One folder per project. Use lowercase names with hyphens (acme-api, acme-web, client-discovery). A project folder isn’t just code — drop Word docs, PDFs, spreadsheets, screenshots, research notes, and meeting transcripts in there too. Claude Code reads and works with all of it, and keeping the full context in one place is how you get the most out of it.

Authenticate

From your project directory (E.g. C:\repo\acme-project1\), run:

claude

• On first launch, the CLI will open your default browser and ask you to sign in with your Anthropic account.
• Complete the sign-in in the browser. The CLI will detect the completed authentication automatically and drop you into an interactive prompt.
• Type /exit and press Enter to end the session. You are now ready to use Claude Code in any project directory.

✓ Highly Recommended: cd to a project first. Claude Code works best when launched from the root of a project. Open a terminal at your repo, then run claude. Claude will automatically scope its context to that directory and its children.

Key CLI commands