Claude Code on macOS - Installation Guide¶

Requirements¶

macOS 11 (Big Sur) or later
4GB RAM minimum (for basic perfomance, use 16GB for optimal use)
Node.js 18+
Internet connection

Step 1: Install Homebrew (if not already installed)¶

Check if Homebrew is installed:

brew --version

If not installed, install Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the post-installation instructions to add Homebrew to your PATH.

Step 2: Install Node.js¶

Check if you already have Node.js:

node --version  # Should be v18+

If Node.js is missing or outdated, install it via Homebrew:

brew install node@20

Verify:

node --version  # Should be v20.x.x or higher
npm --version   # Should be v9.x.x or higher

Alternative: Install via official installer from nodejs.org

Step 3: Install Claude Code¶

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

If installation fails due to permissions:

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

Or configure npm to use a user directory (recommended):

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

Step 4: Verify Installation¶

claude doctor

This will check your installation and report any issues.

Step 5: Launch Claude Code¶

claude

Follow the authentication prompts to log in with your Anthropic account.

Troubleshooting¶

Issue: Command Not Found¶

Symptom: claude: command not found after installation

Fix 1: Ensure npm global bin is in PATH (for Zsh):

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Fix 2: For Bash users:

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

Issue: Permission Denied¶

Symptom: EACCES errors during installation

Fix: Configure npm to use user directory:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

Issue: Node Version Too Old¶

Symptom: Installation fails with Node version warning

Fix: Update Node.js:

brew upgrade node

Or install specific version:

brew install node@20
brew link --overwrite node@20

Issue: Rosetta on Apple Silicon¶

Symptom: Performance issues or compatibility warnings on M1/M2/M3 Macs

Fix: Ensure you're using ARM64 native Node.js:

node -p "process.arch"  # Should output 'arm64'

If it shows x64, reinstall Node.js:

brew uninstall node
brew install node

Issue: IDE Not Detected¶

Symptom: Claude Code doesn't detect your IDE (VS Code, JetBrains, etc.)

Fix: Ensure your IDE is installed in the standard Applications folder and is properly launched at least once. For VS Code, you may need to install the code command:

Open VS Code
Press Cmd+Shift+P
Type "Shell Command: Install 'code' command in PATH"
Restart your terminal

Updates¶

Keep Claude Code up to date:

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

Check current version:

claude --version

Quick Reference¶

claude           # Start session
claude doctor    # Check installation
claude --version # Show version
/help            # In-session help

Uninstallation¶

If you need to remove Claude Code:

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

Note: For the latest documentation and updates, visit docs.claude.com