TokenMix Research Lab · 2026-04-24

Claude Code Install 2026: Mac, Windows, Linux Setup Fixes

Claude Code Install 2026: Mac, Windows, Linux Setup Fixes

Last Updated: 2026-04-30
Author: TokenMix Research Lab
Data checked: 2026-04-30

Use the native Claude Code installer first. Use Homebrew, WinGet, apt/dnf/apk, or npm only when your team needs package-manager control.

Anthropic's current Claude Code setup guide lists native install as the recommended path, supports macOS 13.0+, Windows 10 1809+, Ubuntu 20.04+, Debian 10+, and Alpine Linux 3.19+, and recommends Git for Windows on native Windows. It also says Claude Code requires a Pro, Max, Team, Enterprise, or Console account, while the free Claude.ai plan does not include Claude Code access. The practical 2026 install rule is simple: install the native binary, run claude --version, then run claude doctor before debugging PATH, Git Bash, WSL, or proxy issues.

Table of Contents

Quick Verdict

Item Status What to do
Best default install Confirmed Native installer from Anthropic
macOS package-manager install Confirmed Homebrew cask if your team manages tools through brew
Windows package-manager install Confirmed WinGet, or native installer from PowerShell/CMD
Linux package-manager install Confirmed apt, dnf, or apk when you need OS-managed upgrades
npm install Confirmed fallback Use only if your package manager supports optional dependencies
Windows WSL2 Confirmed option Best for Linux toolchains and sandboxed command execution
Free Claude.ai plan Confirmed limitation Does not include Claude Code access
TokenMix.ai role Inferred Useful for API cost routing, not a replacement for Claude Code login

Install Method Matrix

Method Best for Auto-update behavior Main risk
Native install Most developers Background auto-updates Corporate proxy or endpoint blocking
Homebrew macOS teams with brew policy Manual brew upgrade Stable vs latest cask confusion
WinGet Windows fleet management Manual winget upgrade Git Bash still recommended for shell tools
apt/dnf/apk Linux servers or managed workstations Managed by OS package manager Key verification and repository setup
npm global package Existing Node-based setup npm package update Optional dependencies, global prefix, PATH
WSL2 install Windows developers using Linux tools Same as Linux method Installing in PowerShell but running in WSL, or the reverse

System Requirements

Claude Code is no longer a "just install Node 20" story. The native binary path is cleaner.

Requirement Current official baseline Why it matters
macOS macOS 13.0+ Older macOS versions are outside the supported range
Windows Windows 10 1809+ or Windows Server 2019+ Native Windows is supported
Linux Ubuntu 20.04+, Debian 10+, Alpine 3.19+ Matches official package support
Hardware 4 GB+ RAM, x64 or ARM64 Low-memory machines fail during large repo work
Shell Bash, Zsh, PowerShell, or CMD Native Windows can fall back to PowerShell
Search dependency ripgrep usually included If search fails, check claude doctor first

macOS Install

The fastest macOS route is the native installer:

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

If your team standardizes on Homebrew:

brew install --cask claude-code
claude --version
claude

Use claude-code for the stable channel. Use claude-code@latest only when you intentionally want new releases as soon as they ship. Anthropic says Homebrew installs do not auto-update, so run:

brew upgrade claude-code

or:

brew upgrade claude-code@latest
macOS symptom Likely cause Fix
claude: command not found Shell PATH not refreshed Open a new terminal, then run claude --version
Install succeeds but login hangs Browser, proxy, or firewall issue Try another browser/network; then check auth docs
Brew install works but old version remains Homebrew did not auto-update Run brew upgrade claude-code
Search inside repo fails ripgrep issue Run claude doctor

Windows Install

Windows has two good paths: native Windows or WSL2. Pick based on where the repo lives.

Windows path Use it when Avoid it when
Native Windows + Git Bash Your repo, tools, and terminal are Windows-native You need Linux sandboxing
WSL2 Your repo uses Linux tools, bash scripts, or containers Your files mostly live under Windows-only tooling
WinGet Your team manages Windows software through WinGet You need automatic background updates

Native Windows from PowerShell:

irm https://claude.ai/install.ps1 | iex
claude --version
claude doctor
claude

Native Windows from CMD:

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

WinGet:

winget install Anthropic.ClaudeCode
claude --version
claude

If you use native Windows, install Git for Windows so Claude Code can use Git Bash. Anthropic's docs say Claude Code can fall back to PowerShell when Git Bash is absent, but Git Bash is still the better default for many coding workflows.

For WSL2:

wsl --install

Then inside your WSL distribution:

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

The common Windows mistake is mixing shells. PowerShell commands run in PowerShell. CMD commands run in CMD. WSL commands run inside WSL.

Linux Install

Native installer:

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

Debian/Ubuntu package manager install:

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

Fedora/RHEL package manager install:

sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
enabled=1
gpgcheck=1
gpgkey=https://downloads.claude.ai/keys/claude-code.asc
EOF
sudo dnf install claude-code

Alpine:

wget -O /etc/apk/keys/claude-code.rsa.pub \
  https://downloads.claude.ai/keys/claude-code.rsa.pub
echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories
apk add claude-code

On Alpine and other musl-based distributions, Anthropic documents extra dependencies: libgcc, libstdc++, and ripgrep. Install them first if the native path fails.

npm Fallback

Use npm only when native installers are blocked or your environment already manages global CLIs through npm.

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

The official docs say the npm package requires Node.js 18 or later and installs the same native binary through platform-specific optional dependencies. That detail matters. If optional dependencies are disabled in your npm config, the claude binary may not appear.

npm issue Cause Fix
claude: command not found npm global bin not in PATH Check npm config get prefix, then add its bin path
Binary missing after install Optional dependencies disabled Re-enable optional dependencies and reinstall
Permission error Global npm prefix owned by root/admin Use a user-owned npm prefix or native installer
sudo npm install -g temptation Permission workaround Avoid it; Anthropic warns against sudo npm global install
Node version error Node below 18 Upgrade Node or use native installer

Authentication And API Key Warning

Run claude after installation and follow the browser prompts.

Auth path Best for Cost behavior
Claude Pro/Max login Individual developers Uses subscription access where allowed
Team/Enterprise login Company users Governed by workspace policy
Console/API key API-based usage Billed through API usage
Bedrock/Vertex/Foundry Enterprise cloud routing Billed through cloud/provider setup

Important: Anthropic's Claude Code environment variable docs say that if ANTHROPIC_API_KEY is set, Claude Code uses that key instead of your Claude Pro, Max, Team, or Enterprise subscription. That can create unexpected API charges.

Check before first run:

echo $ANTHROPIC_API_KEY

PowerShell:

$env:ANTHROPIC_API_KEY

If you want subscription login, unset the key before launching Claude Code.

Troubleshooting Matrix

Problem Most likely cause Fast check Fix
claude: command not found Install path not loaded claude --version in a new terminal Reopen shell or fix PATH
PowerShell rejects && CMD command pasted into PowerShell Prompt starts with PS Use the PowerShell installer
CMD does not know irm PowerShell command pasted into CMD Prompt does not start with PS Use the CMD installer
Windows shell tools behave oddly Git Bash missing where bash Install Git for Windows or use WSL2
WSL install not visible in PowerShell Installed inside WSL only Run which claude in WSL Launch Claude Code from WSL
Login opens but never completes Browser/proxy/firewall Try a clean browser profile Check network and auth setup
API bill appears unexpectedly ANTHROPIC_API_KEY is set Print env var Unset the key before using subscription login
Search is broken ripgrep missing or incompatible claude doctor Install/fix ripgrep or Alpine dependencies

Update And Uninstall Matrix

Install method Update command Uninstall command
Native claude update or background auto-update Remove native binary and Claude Code data paths per official docs
Homebrew stable brew upgrade claude-code brew uninstall --cask claude-code
Homebrew latest brew upgrade claude-code@latest brew uninstall --cask claude-code@latest
WinGet winget upgrade Anthropic.ClaudeCode winget uninstall Anthropic.ClaudeCode
apt sudo apt update && sudo apt upgrade claude-code sudo apt remove claude-code
dnf sudo dnf upgrade claude-code sudo dnf remove claude-code
apk apk update && apk upgrade claude-code apk del claude-code
npm npm install -g @anthropic-ai/claude-code@latest npm uninstall -g @anthropic-ai/claude-code

Final Recommendation

Install Claude Code with the native installer, verify with claude --version and claude doctor, then choose Windows native vs WSL2 based on where your project actually runs.

For cost work, separate Claude Code access from API routing. Claude Code is the coding agent. TokenMix.ai is more useful when you need OpenAI-compatible model routing, fallback, and API cost control across providers.

FAQ

What is the best Claude Code install method in 2026?

The best default is Anthropic's native installer. Use Homebrew, WinGet, apt/dnf/apk, or npm when your team needs package-manager governance.

Does Claude Code require Node.js?

Not for the native installer. Node.js 18+ matters for the npm fallback path because @anthropic-ai/claude-code is installed through npm.

Should I install Claude Code on Windows natively or through WSL2?

Use native Windows if your repo and tools are Windows-native. Use WSL2 if your project depends on Linux shell tools, containers, or sandboxed command execution.

Why does claude say command not found after install?

Usually the shell did not reload PATH or the package manager installed the binary somewhere your terminal cannot see. Open a new terminal, run claude --version, then use claude doctor.

Is npm still supported for Claude Code?

Yes, but it should be treated as a fallback. Anthropic documents npm global install, but the recommended path is the native installer.

Can I use Claude Code with a free Claude.ai account?

No. Anthropic's setup page says Claude Code requires Pro, Max, Team, Enterprise, or Console access; the free Claude.ai plan does not include Claude Code access.

Will setting ANTHROPIC_API_KEY change billing?

Yes. Anthropic documents that when ANTHROPIC_API_KEY is set, Claude Code uses that API key instead of subscription access, which can create API usage charges.

Where does TokenMix.ai fit with Claude Code?

Use Claude Code for the coding workflow. Use TokenMix.ai when your app needs OpenAI-compatible routing, fallback, pricing comparison, or lower-cost API paths outside the Claude Code login flow.

Related Articles

Sources