Claude Code · Part 2

Claude Code — Part 2 — Installing Claude Code (and Fixing It When It Breaks)

A practical install walkthrough for Windows, WSL, macOS, and Linux, plus a troubleshooting table for the specific errors IT engineers hit on locked-down or proxied work machines.

By K Shankar R Karanth AI Tools Series Part 2

Quick idea: Installing Claude Code is a single command on any platform, but the errors that follow it are almost always the network, the shell, or the PATH, not the tool itself.

Native Installer

The recommended method on every platform. Auto-updates in the background once installed.

PATH

The single most common install failure. The binary is there, the shell just cannot find it yet.

claude doctor

The built-in diagnostic command for when something installed but does not behave.

Introduction

Part 1 covered what Claude Code actually is and why it is worth an IT engineer’s time. This post is the practical follow-up: getting it installed, confirming it works, and knowing exactly what to check when it does not.

Corporate machines are exactly where installers tend to go wrong. Proxies intercept TLS, endpoint protection blocks child processes, and PATH changes do not take effect until you open a new terminal. None of that means the install failed for a mysterious reason. It almost always maps to one of a small number of known causes.

System Requirements

Claude Code runs on macOS 13.0+, Windows 10 1809+ or Windows Server 2019+, and current Ubuntu, Debian, or Alpine Linux releases. It needs 4 GB or more of RAM, an x64 or ARM64 processor, and an internet connection. It requires a Claude Pro, Max, Team, Enterprise, or Console account, not the free Claude.ai plan.

Practical note: On native Windows, Claude Code runs shell commands through PowerShell by default. Installing Git for Windows is optional but gives Claude Code access to Bash and Git Bash-based tooling as well.

Installing Claude Code

The native installer is the recommended method on every platform. It auto-updates in the background, so you rarely need to think about it again after this step.

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# macOS, Linux, and WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Two Windows alternatives skip the native installer entirely, useful if your environment already standardises on one of them:

# Homebrew (macOS, or Linux with Homebrew installed)
brew install --cask claude-code

# WinGet (Windows)
winget install Anthropic.ClaudeCode

Method	Auto-updates	Notes
Native installer	Yes, automatic	Recommended default on every platform
Homebrew	No, manual	Run `brew upgrade claude-code` to update
WinGet	No, manual	Run `winget upgrade Anthropic.ClaudeCode` to update
npm global install	Depends on npm directory permissions	Requires Node.js 22+; never run with `sudo`

Verify the Installation

Once the installer finishes, open a new terminal and confirm the binary is on your PATH and working.

# Confirm the binary is installed and on PATH
claude --version

# Run the built-in diagnostic for a more detailed check
claude doctor

# Start a session in a project folder
cd C:\Scripts\ADHealthCheck
claude

Key point: The first time you run claude, it opens a browser for login. Claude Code needs a Pro, Max, Team, Enterprise, or Console account; the free Claude.ai plan does not include it.

Troubleshooting Cheat Sheet

Most install failures fall into a handful of categories: PATH, the wrong install command for your shell, corporate TLS interception, or an antivirus scan holding a file open. Work down this table before assuming anything is actually broken.

Symptom	Likely Cause	Fix
`command not found: claude` or `'claude' is not recognized`	The install directory is not on your shell’s PATH yet.	Open a new terminal first. On Windows PowerShell, if it still fails, add `%USERPROFILE%\.local\bin` to your User PATH and restart the terminal.
`'irm' is not recognized`	You ran the PowerShell install command inside CMD, not PowerShell.	Open PowerShell from the Start menu and re-run `irm https://claude.ai/install.ps1 \| iex`, or use the CMD-specific installer instead.
`The token '&&' is not a valid statement separator`	You ran the CMD install command inside PowerShell.	Use the PowerShell installer: `irm https://claude.ai/install.ps1 \| iex`.
`syntax error near unexpected token '<'` or a bare `403`	The install URL returned an HTML error page instead of the script, often a corporate proxy or firewall blocking `downloads.claude.ai`.	Confirm you are in a supported country, then try `winget install Anthropic.ClaudeCode` or `brew install --cask claude-code` as an alternative route.
`TLS connect error`, `unable to get local issuer certificate`	A corporate proxy performing TLS inspection is not trusted by curl or PowerShell.	Point curl at your corporate CA bundle with `curl --cacert C:\path\corporate-ca.pem -fsSL https://claude.ai/install.sh \| bash`, or set `NODE_EXTRA_CA_CERTS` to the same file once Claude Code is installed.
`Failed to fetch version from downloads.claude.ai`	Your network is blocking `downloads.claude.ai` outright.	Set the `HTTPS_PROXY` and `HTTP_PROXY` environment variables to your proxy address before installing, or switch networks.
`The process cannot access the file ... because it is being used by another process`	A previous install attempt is still running, or antivirus is scanning the partially downloaded binary.	Close other install windows, then clear `%USERPROFILE%\.claude\downloads` and re-run the PowerShell installer.
`Claude Code on Windows requires either Git for Windows (for bash) or PowerShell`	Neither shell was found, or an EDR/AppLocker policy is blocking the check.	Install Git for Windows and select “Add to PATH” during setup, or point Claude Code at an existing Git install via `CLAUDE_CODE_GIT_BASH_PATH` in `settings.json`.
`Claude Code does not support 32-bit Windows`	You launched “Windows PowerShell (x86)” instead of the 64-bit PowerShell entry.	Close that window, open plain “Windows PowerShell” from the Start menu, and re-run the install command.

Production note: If your organisation terminates and re-signs TLS at the network edge, the corporate CA certificate route is almost always the fix, not disabling certificate checks. Ask your security or network team for the CA bundle rather than working around it.

Final Thoughts

Installation itself is a one-line command. Nearly every real install problem an IT engineer hits comes from the environment around it: PATH not refreshed yet, the wrong shell for the command you copied, or a corporate network doing something to the connection before it reaches downloads.claude.ai.

Once claude --version returns a version number, the tool itself is working correctly and any remaining issue is configuration, not installation.

Key takeaway: If claude --version prints a version, the install worked. Anything after that is PATH, network, or account configuration, and claude doctor is the first command to run to tell them apart.

Next in this series

Next, we create and navigate a real project: what happens the first time you point Claude Code at a folder, and how to work with it session to session.