How to Install Claude Code on Mac (2026): Homebrew, Native, and npm

Requirements

• macOS 13 (Ventura) or later. Older versions are not supported.
• Apple Silicon (M1/M2/M3/M4/M5) or Intel Mac. The native installer provides a universal binary.
• Paid Anthropic account: Claude Pro ($20/month), Claude Max ($100-200/month), Teams, Enterprise, or Anthropic Console with API credits. The free Claude.ai plan does not include Claude Code.
• Terminal: Terminal.app, iTerm2, Warp, or any terminal emulator.

Native Installer (Recommended)

The fastest path. No Node.js, no package manager, no dependencies. Downloads a universal binary, installs to ~/.local/bin, and adds the PATH entry to your ~/.zshrc. Auto-updates in the background.

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

After the script finishes, open a new terminal window (or run source ~/.zshrc) so your shell picks up the new PATH entry. Then verify:

claude --version

Homebrew

If you manage your Mac tools through Homebrew, this keeps Claude Code in the same system. It installs as a cask (a macOS application binary, not a formula compiled from source).

# Install
brew install --cask claude-code

# Verify
claude --version

Homebrew puts the binary on your PATH automatically. No shell config changes needed.

The tradeoff: no auto-updates. You need to update manually:

brew upgrade claude-code

npm via nvm (Legacy)

The npm method is no longer recommended but still works. Use it if you need to pin a specific Claude Code version or your workflow already centers on npm.

Step 1: Install nvm and Node.js

Do not use the Node.js installer from nodejs.org. It installs to a system directory and causes permission errors with global packages. Use nvm instead:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# Reload your shell
source ~/.zshrc

# Install Node.js 22 (LTS)
nvm install 22
nvm use 22

Step 2: Install Claude Code

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

Alternatively, if you already have Homebrew, brew install node also installs Node.js to a user-accessible location and avoids permission issues.

Gatekeeper and Security

macOS Gatekeeper may block Claude Code on first run with this message:

"claude" Not Opened. Apple could not verify "claude" is free of malware that may harm your Mac or compromise your privacy.

Two fixes:

Fix 1: System Settings (GUI)

Open System Settings > Privacy & Security. Scroll down. You'll see a message about claude being blocked. Click Allow Anyway. Run claude again in your terminal.

Fix 2: Remove quarantine flag (Terminal)

# Find where claude is installed
which claude

# Remove the quarantine attribute (use the path from above)
xattr -d com.apple.quarantine $(which claude)

Shell and PATH Configuration

macOS uses zsh as the default shell since Catalina (10.15). The native installer adds the PATH export to ~/.zshrc. If you changed your default shell to bash, the installer targets ~/.bash_profile instead.

If claude: command not found after install

# Check if the PATH line exists
grep -n "claude" ~/.zshrc

# If missing, add it manually
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

# Reload
source ~/.zshrc

# Verify
which claude

If you use bash instead of zsh

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

Fish shell

fish_add_path ~/.local/bin

After any PATH change, verify with which claude. It should print something like /Users/yourname/.local/bin/claude.

Apple Silicon vs Intel

The native installer downloads a universal binary that runs natively on both ARM64 (Apple Silicon) and x86_64 (Intel). No Rosetta 2 translation needed for the Claude Code binary itself.

Claude Code is a thin client that sends requests to Anthropic's API. The actual LLM runs server-side. So there is no performance difference between Apple Silicon and Intel for Claude Code itself. The bottleneck is network latency and API response time, not your local CPU.

Terminal Setup

Your terminal choice affects Claude Code's features. Notifications, split panes for agent teams, and multiline input handling all depend on terminal support.

Terminal configuration commands

# Inside Claude Code, run:
/terminal-setup    # Configure Shift+Enter for multiline input
/config            # Set light/dark theme, notification preferences

iTerm2 + tmux for agent teams

If you use Claude Code's agent teams feature (multiple Claude instances working in parallel), iTerm2 with tmux control mode gives you native pane management:

# Start tmux in control mode (the -CC flag is important)
tmux -CC new-session -s agents

# iTerm2 maps tmux panes to native iTerm2 split panes
# Each agent gets its own visible pane

Post-Install Configuration

1. Authenticate

Run claude in any project directory. On first launch, it opens your browser for OAuth authentication. Authorize Claude Code and a session token is stored locally at ~/.claude/.

cd your-project
claude
# Browser opens for authentication
# Session token stored automatically after authorization

2. Generate CLAUDE.md

The single most impactful configuration step. CLAUDE.md gives Claude persistent context about your project: build commands, conventions, architecture decisions.

# Inside Claude Code:
/init

# This analyzes your codebase and creates a starter CLAUDE.md
# Edit it to add project-specific conventions

3. Set up API key (optional)

For headless usage or CI, set your API key in your shell config instead of using browser auth:

# Add to ~/.zshrc
export ANTHROPIC_API_KEY=sk-ant-...

# Reload
source ~/.zshrc

MCP Servers

MCP (Model Context Protocol) servers extend Claude Code with external tools. Add them once and they persist across sessions.

# Add an HTTP-based MCP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Add a local stdio-based MCP server
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# List configured servers
claude mcp list

# Remove a server
claude mcp remove github

Recommended: WarpGrep

WarpGrep is an RL-trained code search MCP server built by Morph. It runs searches in a separate context window so your main Claude session stays clean. Instead of dumping entire files, it returns precise file and line ranges. This matters at scale: in large codebases, naive file search eats context and degrades Claude's reasoning quality.

Troubleshooting

claude: command not found

Your shell hasn't loaded the PATH update. Open a new terminal window. If that doesn't work:

# Check if claude binary exists
ls -la ~/.local/bin/claude

# Check your PATH
echo $PATH | tr ':' '\n' | grep -i claude

# If ~/.local/bin is missing from PATH, add it
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Gatekeeper blocks the binary

System Settings > Privacy & Security > Allow Anyway. Or remove the quarantine attribute:

xattr -d com.apple.quarantine $(which claude)

Permission denied errors on /tmp/claude-*

After macOS upgrades, temporary directory permissions can break. Claude Code writes to /tmp/claude-<UID>/ for workspace state. Fix permissions:

# Remove stale tmp directory
rm -rf /tmp/claude-$(id -u)

# Restart Claude Code
claude

npm EACCES errors

Do not use sudo. Install nvm, then reinstall Claude Code through nvm-managed Node.js. See the npm via nvm section above.

Authentication fails

• Check that you're logged into claude.ai in the browser that opens
• Verify your account is on a paid plan (Pro, Max, Teams, or Enterprise)
• Run claude logout then claude to re-authenticate
• Try a different browser if the redirect hangs

Run /doctor

Inside Claude Code, /doctor auto-diagnoses most configuration issues: Node.js version, auth state, MCP server health, file permissions. Run it before debugging manually.

Frequently Asked Questions

How do I install Claude Code on a Mac?

The recommended method is the native installer: curl -fsSL https://claude.ai/install.sh | bash in Terminal. You can also use Homebrew (brew install --cask claude-code) or npm (npm install -g @anthropic-ai/claude-code, requires Node.js 18+).

Does Claude Code work on Apple Silicon Macs?

Yes. The native installer downloads a universal binary that runs natively on Apple Silicon (M1, M2, M3, M4, M5) and Intel Macs. No Rosetta 2 needed for the Claude Code binary.

Why does Gatekeeper block Claude Code?

macOS Gatekeeper flags any binary downloaded outside the App Store that isn't Apple-notarized. Go to System Settings > Privacy & Security and click Allow Anyway. Or run xattr -d com.apple.quarantine $(which claude) to clear the quarantine flag.

Do I need Xcode to run Claude Code?

Claude Code itself doesn't require Xcode. But it calls git and other developer tools that ship with Xcode Command Line Tools. Install them with xcode-select --install.

Which terminal should I use?

iTerm2 is the best choice for power users. It supports split panes, tmux control mode for agent teams, and native notifications. Terminal.app works for basic usage. Warp is fast but may need classic input mode. VS Code and Cursor integrated terminals work well too.

Why can't my Mac find the claude command?

Your shell hasn't loaded the new PATH. Open a new terminal window, or run source ~/.zshrc. The native installer adds export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc automatically.

Homebrew or native installer?

Native installer for auto-updates. Homebrew for package manager control (brew list, brew uninstall). If in doubt, use the native installer.

Does Claude Code auto-update on Mac?

Only with the native installer. Homebrew requires brew upgrade claude-code. npm requires npm update -g @anthropic-ai/claude-code.

Related Guides

• Install Claude Code (All Platforms)
• CLAUDE.md Guide
• Claude Code vs Cursor
• Claude Code vs Windsurf