Run curl -fsSL https://claude.ai/install.sh | bash, restart your shell, and run claude in a project directory. That is the native install: no Node.js, no Homebrew, and it updates itself in the background. brew install --cask claude-code is the alternative if you already manage everything through Homebrew, at the cost of manual upgrades. npm still works and is the route to use when you need a pinned version. Claude Code requires macOS 13.0 or later on Apple Silicon or Intel, as of August 2026.
- The native installer is one command, needs no Node.js, and self-updates.
- Homebrew ships two casks:
claude-codetracks stable,claude-code@latesttracks latest. - Homebrew and npm installs do not auto-update. Native ones do.
- macOS 13.0 is the floor. Older versions fail with a
dylderror, not a clear message. - Apple Silicon and Intel are both native. Rosetta is not involved.
- Two installs on PATH is the most common cause of "it updated but nothing changed".
The fastest route
curl -fsSL https://claude.ai/install.sh | bashRestart your shell
The installer puts the binary at ~/.local/bin/claude and adds that directory to your PATH through your shell profile. The shell you ran it from will not have picked that up.
exec $SHELL -lVerify
claude --version
# 2.1.211 (Claude Code)
claude doctorclaude doctor prints read-only installation and settings diagnostics without starting a session: install health, settings-file validation errors, the result of the last update attempt, and any warnings with suggested fixes. Reach for it before reinstalling anything.
Start in a project
cd ~/code/your-project
claudeFirst run opens a browser to authenticate. Claude Code requires a Pro, Max, Team, Enterprise, or Console account as of August 2026; the free Claude.ai plan does not include access.
Homebrew, done properly
Homebrew ships Claude Code as a cask, and it ships two of them. Which one you install decides your release channel, because the autoUpdatesChannel setting does not apply to Homebrew installs.
| Cask | Channel | Upgrade with |
|---|---|---|
claude-code | Stable, roughly a week behind, skips releases with major regressions | brew upgrade claude-code |
claude-code@latest | Latest, new versions as soon as they ship | brew upgrade claude-code@latest |
# stable channel
brew install --cask claude-code
# or track latest
brew install --cask claude-code@latest
# upgrades are manual
brew upgrade claude-code
# Homebrew keeps old versions on disk
brew cleanupThe three routes compared
All three install the same native binary. The difference is who owns updates.
| Route | Install | Auto-updates | Channel control | Fragility |
|---|---|---|---|---|
| Native installer | curl ... | bash | Yes, in the background | autoUpdatesChannel setting | Low |
| Homebrew | brew install --cask claude-code | No | By cask name | Low, if you already use brew |
| npm global | npm i -g @anthropic-ai/claude-code | Only if the npm prefix is writable | By version pin | Highest |
Moving off a global npm install
There is no migration ritual. Install the native build, confirm which binary is winning, then remove the npm one. Your configuration and history are outside the package and survive all of it.
# 1. install the native build
curl -fsSL https://claude.ai/install.sh | bash
exec $SHELL -l
# 2. see every claude on PATH, in PATH order
which -a claude
# 3. a native install is a symlink into the versions directory
ls -la ~/.local/bin/claude
# 4. remove the npm one
npm uninstall -g @anthropic-ai/claude-code
# 5. and the legacy local install older versions created
rm -rf ~/.claude/local
claude doctormacOS specifics worth knowing
- macOS 13.0 or later is required, as of August 2026, on x64 or ARM64 with at least 4 GB of RAM. Below that the binary fails with a
dyldload error rather than a friendly version check, and Homebrew will not save you because it downloads the same binary. - Apple Silicon and Intel are both native. The installer picks
darwin-arm64ordarwin-x64for you. Rosetta is not required and not used. - Credentials live in the macOS Keychain, not a plaintext file, which is why the first run may prompt for Keychain access. Bare mode (
claude --bare) deliberately never reads the Keychain, which is why scripted calls needANTHROPIC_API_KEYinstead. - Xcode command line tools are worth having anyway:
xcode-select --install. Git and the compiler toolchain come with them, and a great deal of what an agent tries to run assumes both. - Protected directories are a real trap. Running an agent in
~/Desktop,~/Documents, or~/Downloadstriggers macOS privacy prompts aimed at your terminal application. Keep projects somewhere ordinary such as~/code.
Troubleshooting
Ranked by how often it is the actual cause.
| Symptom | Cause | Fix |
|---|---|---|
zsh: command not found: claude | ~/.local/bin not on PATH | echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc, then a new terminal |
| Worked, then vanished after a Node upgrade | npm global install under the old Node prefix | Install natively and npm uninstall -g @anthropic-ai/claude-code |
which claude shows an unexpected path | Two installs | which -a claude, keep one |
dyld: Symbol not found or built for Mac OS X 13.0 | macOS older than 13.0 | Update macOS. No install method works around this. |
Illegal instruction | CPU without AVX, or an architecture mismatch | Check uname -m; pre-2013 Intel Macs and some VMs lack AVX |
claude doctor hangs with no output | A directory sits at a shell config path such as ~/.zshrc | Remove it; fixed in v2.1.214 and later |
| Keychain prompts on every launch | The credential is being re-created each time | Allow always, then claude doctor |
| Permission errors inside a project folder | Project is under Desktop, Documents, or Downloads | Move it to ~/code |
| Anything else | Unknown | claude doctor first, then claude --version |
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude
# Homebrew instead
brew uninstall --cask claude-code
# settings, memory, and session history (only if you mean it)
rm -rf ~/.claude
rm ~/.claude.jsonQuestions people ask
Run curl -fsSL https://claude.ai/install.sh | bash, restart your shell with exec $SHELL -l, then run claude in a project directory. No Node.js and no Homebrew are required for this route, and it updates itself in the background.
Yes: brew install --cask claude-code for the stable channel, or brew install --cask claude-code@latest for the latest channel. Homebrew installs do not auto-update, so run brew upgrade yourself or set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1.
Release channel. claude-code tracks stable, which is typically about a week behind and skips releases with major regressions. claude-code@latest gets new versions as soon as they ship.
Only if you need a pinned version, as in CI or a container image. On a personal Mac the native installer is simpler, self-updating, and unaffected by Node upgrades, which are the usual cause of a global npm install disappearing.
Run the native installer, restart your shell, check which -a claude to confirm the native binary is first, then npm uninstall -g @anthropic-ai/claude-code. Also remove ~/.claude/local if an older version created it. Your settings and history are untouched.
Yes, natively on both Apple Silicon and Intel. The installer picks the darwin-arm64 or darwin-x64 build and Rosetta is not required.
Most often because the project sits under Desktop, Documents, or Downloads, which macOS protects. The prompts target your terminal application and an agent has no way to show them to you. Move the project to somewhere ordinary such as ~/code.
macOS 13.0 or later, as of August 2026. On older versions the binary fails with a dyld error or a Symbol not found message referencing libicucore, and no alternative install method avoids it because they all ship the same binary.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.