Claude Code Installation Guide: Native, npm, macOS, Linux, and Windows¶

For / Key Points

For: Developers installing Claude Code for the first time or moving from the legacy npm installation to the recommended native installer

Key Points:

The native installer is the default choice on macOS, Linux, WSL, and Windows because it does not require Node.js and supports automatic updates
Homebrew and WinGet suit managed package workflows; npm remains an alternative that requires Node.js 18 or later
Run claude doctor after installation to confirm the executable, update method, and any PATH conflict

Choose an installation method first¶

Anthropic recommends the native installation. It installs a standalone executable, does not require Node.js, and uses background updates by default.¹

Method	Best fit	Node.js	Updates
Native installer	Personal machines, WSL, normal developer workstations	Not required	Automatic
Homebrew	macOS/Linux environments standardized on brew	Not required	`brew upgrade`
WinGet	Managed Windows endpoints	Not required	`winget upgrade`
npm	Existing Node.js environments and compatibility needs	18+	Reinstall `@latest`
apt/dnf/apk	Organizations using signed Linux repositories	Not required	Package manager

Use the native installer unless endpoint policy requires a package manager. npm is still supported, but it is no longer the simplest default for a new installation.

Install on macOS, Linux, or WSL¶

Run the official installer:

curl -fsSL https://claude.ai/install.sh | bash

Open a new shell and verify the result:

claude --version
claude doctor

On macOS, Homebrew offers two channels:

# Stable channel, generally about one week behind latest
brew install --cask claude-code

# Latest channel
brew install --cask claude-code@latest

Package-manager installations do not use Claude Code's built-in auto-updater. Upgrade the Homebrew package explicitly:

brew upgrade --cask claude-code

Project dependencies are separate

The native Claude Code installation does not need Node.js, but your repository may still require language runtimes, build tools, containers, or language servers.

Install on Windows¶

The native Windows build requires Git for Windows. If you use WSL, run the Linux installer inside the WSL shell rather than installing the Windows binary into WSL.¹

PowerShellCommand PromptWinGet

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

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

winget install Anthropic.ClaudeCode

Upgrade a WinGet-managed installation with:

winget upgrade Anthropic.ClaudeCode

For WSL projects, keep the repository in the Linux filesystem when practical. File-heavy operations can be slower under /mnt/c/....

Use npm only when it fits your environment¶

The npm route requires Node.js 18 or later. Avoid sudo npm install -g, which can introduce permission and ownership conflicts.¹

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

Upgrade by explicitly installing the latest release. Do not rely on npm update -g for this package.

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

The npm package now installs a platform-specific native binary, but Node.js, npm, and global PATH management still add dependencies that the native installer avoids.

Authenticate and verify the first session¶

Start Claude Code inside a project:

cd /path/to/project
claude

The first run opens browser authentication. Supported account paths include Claude Pro, Max, Team, Enterprise, Anthropic Console, and supported third-party cloud providers. The free Claude.ai plan by itself does not include Claude Code.²

Begin with a read-only request:

> Read this repository and explain its structure without changing files.

This confirms both the working directory and the initial permission flow before edits are allowed.

Select an update channel¶

Native installations support latest and stable channels. stable is useful when a workstation should receive releases after roughly one week of validation.³

{
  "autoUpdatesChannel": "stable"
}

For team deployments, distribute this through managed settings instead of asking each developer to configure it manually.

Fix old or duplicate installations¶

The most common migration problem is leaving both npm and native executables on PATH. Identify every executable first:

which -a claude       # macOS/Linux/WSL
where.exe claude      # Windows
claude doctor

If the npm installation is no longer needed:

npm uninstall -g @anthropic-ai/claude-code
hash -r
claude doctor

If the shell reports command not found, apply the PATH instruction shown by the installer and reopen the terminal. Anthropic's troubleshooting guide documents native binary locations and migration diagnostics.⁴

Minimal post-install checklist¶

claude --version succeeds
claude doctor reports the intended installation method
The authenticated account is the intended personal or organizational identity
A read-only request succeeds in a test repository
Organization users have agreed on permissions, data boundaries, and the update channel

After these checks, move on to repository instructions and permission design.

Summary¶

Prefer the native installer unless endpoint policy requires a package manager
Choose Homebrew, WinGet, or npm only when that distribution path fits the environment
Run claude doctor and remove a stale npm executable before beginning project work