Claude Code for macOS

Native macOS installation with Homebrew. Optimized for both Intel and Apple Silicon Macs. The easiest platform to get started with Claude Code.

Easiest Installation

Very Quick Installation

For experienced users - get Claude Code running in 3 commands

macOS Quick Setup 
# Install Node.js (macOS with Homebrew)
brew install node

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Run Claude Code
claude

Beginner Path

Step-by-Step Guide

New to command line or development tools? Follow our detailed guide with explanations.

  • Homebrew installation explained
  • Terminal basics and tips
  • Node.js setup walkthrough
  • First-time user guidance
Start Beginner Guide

Professional Path

Quick Setup

Experienced developer? Jump straight to advanced configurations and enterprise features.

  • One-command installation
  • Advanced MCP configurations
  • Development environment optimization
  • Enterprise deployment options
Quick Setup

System Requirements

Claude Code works natively on macOS with minimal requirements.

macOS Version macOS 10.15 Catalina or later (recommended: macOS 12+)
Processor Intel x64 or Apple Silicon (M1/M2/M3)
Memory 4GB RAM minimum (8GB+ recommended)
Storage 1GB free space for Node.js and Claude Code
Network Internet connection for installation and API access
Account Claude Max subscription OR Anthropic API key

Great News! macOS is the most straightforward platform for Claude Code installation. No virtualization or compatibility layers needed.

Beginner Installation Guide

Follow these detailed steps to install Claude Code on macOS. Perfect for developers new to command line tools.

1 Install Homebrew Package Manager

5 minutes

Homebrew is the most popular package manager for macOS. It makes installing development tools simple and reliable.

What is Homebrew?

Homebrew is like an app store for command-line tools. It automatically handles downloads, installations, and updates for thousands of development tools including Node.js.

Installation Command

Open Terminal (⌘ + Space, type "Terminal") and run:

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

This command downloads and runs the official Homebrew installer. You'll be prompted for your password.

Follow the Installation Prompts

  1. Enter your macOS password when prompted
  2. Press Enter to continue when asked
  3. Wait for the installation to complete (5-10 minutes)
  4. Follow any additional instructions shown

Add Homebrew to PATH (Apple Silicon Macs)

If you have an M1/M2/M3 Mac, you may need to add Homebrew to your PATH:

# Add Homebrew to PATH
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Verify Installation

# Check if Homebrew is installed correctly
brew --version

# Should output something like: Homebrew 4.x.x

Tip: If you see "command not found" for brew, restart Terminal or run the PATH command above.

2 Install Node.js

3 minutes

Node.js is the JavaScript runtime that Claude Code requires. We'll install the latest LTS (Long Term Support) version.

Install Node.js with Homebrew

# Install Node.js (includes npm)
brew install node

# Verify installation
node --version
npm --version

This installs both Node.js and npm (Node Package Manager) which we'll use to install Claude Code.

What You Should See

# Expected output (versions may be newer)
$ node --version
v20.x.x

$ npm --version
10.x.x

Configure npm (Optional but Recommended)

Set up npm to avoid permission issues with global packages:

# Create directory for global packages
mkdir -p ~/.npm-global

# Configure npm to use this directory
npm config set prefix ~/.npm-global

# Add to PATH in your shell profile
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc

# Reload shell configuration
source ~/.zshrc

Success! Node.js is now installed and ready to use.

3 Install Claude Code

2 minutes

Now we can install Claude Code using npm. This downloads the latest version from the official repository.

Install Claude Code Globally

# Install Claude Code globally
npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version

The -g flag installs Claude Code globally, making it available from any directory.

Test the Installation

# Check if Claude Code is in PATH
which claude

# Should output something like: /usr/local/bin/claude or ~/.npm-global/bin/claude

Apple Silicon Specific (M1/M2/M3 Macs)

If you encounter any issues on Apple Silicon, try:

# Force ARM64 architecture
arch -arm64 npm install -g @anthropic-ai/claude-code

Excellent! Claude Code is now installed on your Mac.

4 Set Up Authentication

3 minutes

Configure Claude Code to work with your Anthropic account. You can use either Claude Max or an API key.

Option A: Claude Max (Recommended)

Best for regular users ($20/month):

  1. Navigate to a project directory
  2. Run claude
  3. Follow OAuth prompts in browser
  4. Complete authentication
# Navigate to your project
cd ~/Projects/your-project

# Start Claude Code
claude

Option B: API Key

For pay-per-use or enterprise:

  1. Get API key from Anthropic Console
  2. Set environment variable
  3. Add to shell profile
# Set API key
export ANTHROPIC_API_KEY=your_key_here

# Add to shell profile
echo 'export ANTHROPIC_API_KEY=your_key' >> ~/.zshrc
source ~/.zshrc

Note: macOS uses zsh as the default shell. If you're using bash, replace ~/.zshrc with ~/.bash_profile.

5 First Use and Testing

5 minutes

Test Claude Code with your first project and learn the basic workflow.

Create a Test Project

# Create a new project directory
mkdir ~/claude-test
cd ~/claude-test

# Create a simple JavaScript file
echo "console.log('Hello Claude!');" > hello.js

# Create a README
echo "# My First Claude Code Project" > README.md

Start Claude Code

# Start Claude Code in your project
claude

# Try some basic commands
> "Explain what this JavaScript file does"
> "/init"  # Generate project documentation
> "/help"  # See all available commands
> "/status" # Check system status

Basic Commands to Try

  • /init - Generate CLAUDE.md documentation
  • /help - Show all available commands
  • /model claude-sonnet-4 - Switch AI models
  • /clear - Clear conversation context
  • /exit - Exit Claude Code

Congratulations! You've successfully installed and tested Claude Code on macOS. You're ready to start AI-powered development!

Professional Installation Guide

Quick setup for experienced developers with advanced configurations and optimization tips.

One-Command Installation

2 minutes

Complete installation in a single command. Assumes you have Homebrew installed. 

# Complete installation (if Homebrew is already installed)
brew install node && npm install -g @anthropic-ai/claude-code

# Or full installation from scratch
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" && \
brew install node && \
npm install -g @anthropic-ai/claude-code

Verify Installation

# Quick verification
claude --version && echo "✅ Claude Code installed successfully"

Development Environment Optimization

Optimize your macOS development environment for Claude Code.

Shell Configuration

Add to ~/.zshrc or ~/.bash_profile:

# Claude Code environment
export ANTHROPIC_API_KEY=your_key
export CLAUDE_MODEL=claude-sonnet-4
export MCP_DEBUG=false

# Node.js optimization
export NODE_OPTIONS="--max-old-space-size=4096"

# npm global packages
export PATH=~/.npm-global/bin:$PATH

# Homebrew (Apple Silicon)
eval "$(/opt/homebrew/bin/brew shellenv)"

Global Configuration

Create ~/.claude.json:

{
  "defaultModel": "claude-sonnet-4",
  "permissions": {
    "allowedTools": ["Edit", "Bash(git*)"],
    "deniedTools": ["Bash(rm*)"]
  },
  "preferences": {
    "autoCompact": true,
    "compactThreshold": 50000
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Projects"]
    }
  }
}

IDE Integration Setup

Set up Claude Code with popular macOS development environments.

VS Code Integration

# Install VS Code extension
code --install-extension anthropic.claude-code

# Connect Claude Code to VS Code
claude /ide

# Use keyboard shortcuts
# Cmd+Esc to access Claude Code
  • Inline edit suggestions
  • Context sharing with open files
  • Visual diffs for changes

Terminal Integration

# iTerm2 integration
echo 'alias cc="claude"' >> ~/.zshrc

# Terminal optimization
claude /terminal-setup

# Add to iTerm2 profile for quick access
# Cmd+T -> New tab with claude auto-start
  • Quick access aliases
  • Terminal optimization
  • iTerm2 profile setup

Advanced MCP Configuration

Set up Model Context Protocol servers for enhanced capabilities. 

# Install essential MCP servers
npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-github
npm install -g @modelcontextprotocol/server-puppeteer

# Quick MCP setup
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Projects
claude mcp add github -s user -- env GITHUB_TOKEN=your_token npx -y @modelcontextprotocol/server-github

Project-Specific MCP

Create .claude.json in your project root:

{
  "mcpServers": {
    "project-filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"]
    },
    "project-specific": {
      "command": "npx",
      "args": ["-y", "@your-org/custom-mcp-server"]
    }
  }
}

Performance Optimization

Optimize Claude Code performance on macOS for large projects.

Memory Optimization

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=8192"

# For large codebases
export NODE_OPTIONS="--max-old-space-size=16384"

# Add to shell profile
echo 'export NODE_OPTIONS="--max-old-space-size=8192"' >> ~/.zshrc

File System Optimization

# Exclude large directories
echo "node_modules/
.git/
dist/
build/
*.log" > .claudeignore

# Use SSD for better performance
# Keep projects on internal SSD, not external drives

macOS-Specific Tips & Tricks

Make the most of Claude Code on macOS with these platform-specific optimizations.

Keyboard Shortcuts

Action Shortcut
Open Terminal ⌘ + Space → "Terminal"
New Terminal Tab ⌘ + T
Claude Code in IDE ⌘ + Esc
Paste in Terminal ⌘ + V
Clear Terminal ⌘ + K

Spotlight Integration

Quick Access

  1. Press ⌘ + Space
  2. Type "Terminal"
  3. Press Enter
  4. Type claude

Create Automator Shortcut

  1. Open Automator
  2. Create "Quick Action"
  3. Add "Run Shell Script"
  4. Set script to: cd ~/Projects && claude
  5. Save as "Start Claude Code"

Finder Integration

Open Terminal Here

Right-click in Finder and select "New Terminal at Folder"

Quick Claude Access

# Create alias for quick access
echo 'alias ccd="cd \$1 && claude"' >> ~/.zshrc

# Usage: ccd ~/Projects/my-project

Dock Integration

Add Terminal to Dock

  1. Open Terminal
  2. Right-click Terminal icon in Dock
  3. Select "Options" → "Keep in Dock"

Create Claude Code App

# Create app bundle (advanced)
# Use Platypus or create Automator application
# Set to run: cd ~/Projects && claude

macOS Troubleshooting

Solutions to common issues specific to macOS installations.

Installation Issues

Homebrew installation fails

# Check Xcode Command Line Tools
xcode-select --install

# If already installed, reset
sudo xcode-select --reset

Permission denied errors

# Fix Homebrew permissions
sudo chown -R $(whoami) /opt/homebrew

# For Intel Macs
sudo chown -R $(whoami) /usr/local

Command not found: brew

# Add Homebrew to PATH (Apple Silicon)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# For Intel Macs
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile

Runtime Issues

Claude Code not found

# Check npm global directory
npm config get prefix

# Add to PATH if needed
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc

Apple Silicon compatibility

# Force ARM64 architecture
arch -arm64 npm install -g @anthropic-ai/claude-code

# Check architecture
uname -m  # Should show arm64 for Apple Silicon

Network connectivity issues

# Check DNS resolution
nslookup api.anthropic.com

# Test connectivity
curl -I https://api.anthropic.com

🎉 macOS Installation Complete!

Congratulations! You've successfully installed Claude Code on macOS. Here's what to explore next:

Explore Features Setup MCP View Examples

Need help? Check our troubleshooting guide or visit the community resources.

All Claude Commands