Mac is the best-supported platform for Claude Code. The toolchain installs cleanly via Homebrew, the default zsh shell handles environment variables well, and iTerm2 gives you a terminal that works well with CLI-heavy workflows. This guide covers the full setup from a clean Mac to a productive Claude Code session. Once your environment is ready, the Claude Code Course is the fastest way to become productive with the tool.
If you are on Windows, this guide does not apply. Follow the Claude Code Windows WSL2 setup guide instead.
Recommended Setup Path
The fastest path to a stable Claude Code installation on Mac uses three tools in sequence: Homebrew for package management, nvm for Node.js version management, and npm for the Claude Code install itself. Using nvm instead of the system Node.js or a direct nodejs.org installer gives you the ability to switch Node versions per project and avoids the permission errors that come with system-level npm installs.
Setup Overview
| Step | Tool | Command |
|---|---|---|
| 1 | Install Homebrew | /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" |
| 2 | Install nvm via Homebrew | brew install nvm |
| 3 | Configure nvm in shell | Add nvm setup block to ~/.zshrc |
| 4 | Install Node 20 LTS | nvm install 20 |
| 5 | Install Claude Code | npm install -g @anthropic-ai/claude-code |
| 6 | Set API key | Add to ~/.zshrc |
| 7 | Verify | claude --version |
Step 1: Install Homebrew
Homebrew is the standard package manager for Mac. If you already have it, skip this step.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"On Apple Silicon Macs (M1, M2, M3, M4), Homebrew installs to /opt/homebrew. On Intel Macs, it installs to /usr/local. After installation, the installer will print a message asking you to add Homebrew to your PATH. Follow those instructions before continuing.
You can confirm Homebrew is working with brew --version.
Step 2: Install nvm via Homebrew
nvm (Node Version Manager) lets you install and switch between Node.js versions without touching system-level directories. Install it via Homebrew:
brew install nvmAfter the install completes, Homebrew will print instructions for configuring nvm in your shell. Add the following block to your ~/.zshrc file (create it if it does not exist):
export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"
[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"On Intel Macs, replace /opt/homebrew with /usr/local. After editing ~/.zshrc, reload it:
source ~/.zshrcConfirm nvm is active with nvm --version.
Step 3: Install Node 20 LTS
Install Node.js 20 LTS and set it as your default:
nvm install 20
nvm use 20
nvm alias default 20Verify the active version:
node --version
# Should output v20.x.xNode 20 LTS is the recommended version because it has the longest support window and the broadest compatibility with npm packages. Claude Code requires Node 18 or higher, but 20 LTS is the safer long-term choice.
Step 4: Install Claude Code
With Node 20 active, install Claude Code globally:
npm install -g @anthropic-ai/claude-codeBecause nvm manages Node in your home directory, this install does not require sudo and will not produce permission errors. Verify the install:
claude --versionStep 5: Configure Your Shell for Authentication
Add your Anthropic API key to ~/.zshrc so it is available in every terminal session:
export ANTHROPIC_API_KEY=your_api_key_hereGet your API key from console.anthropic.com under API Keys. After adding the line, reload your shell:
source ~/.zshrcIf you use a Claude Max subscription instead of API key billing, run claude auth login after installation. This opens a browser OAuth flow and stores a token locally.
You do not need the ANTHROPIC_API_KEY variable in your shell if you use Claude Max. For a full comparison of both options, see Claude Code authentication setup.
Add your API key to
~/.zshrcrather than setting it as a one-time export in a terminal session. One-time exports disappear when you close the window, which causes confusing authentication errors in new sessions.
Recommended Terminal: iTerm2
The default Mac Terminal app works with Claude Code, but iTerm2 offers several advantages for CLI-heavy workflows:
- Split panes, run Claude Code in one pane and your dev server in another
- Better color rendering for improved readability in long sessions
- Configurable profiles that can set your working directory automatically
Download iTerm2 from iterm2.com. No special configuration is required for Claude Code compatibility. zsh is the default shell on macOS Catalina and later, which is what you want.
Claude Code with VS Code
Many developers run Claude Code in the VS Code integrated terminal alongside their editor. To open VS Code from the terminal in any directory:
code .If code is not a recognized command, open VS Code, press Cmd+Shift+P, type Shell Command: Install 'code' command in PATH, and run it. After that, code . opens VS Code in the current directory.
Inside VS Code, open the integrated terminal with Ctrl+` and run claude from there.
Claude Code can read any file you have open in VS Code, and you can switch between the editor and the Claude Code session without leaving the application.
Useful Mac Shell Aliases
Add these aliases to your ~/.zshrc to speed up common Claude Code workflows:
# Start a Claude Code session in the current directory
alias cc="claude"
# Open Claude Code with a specific task passed as argument
alias cct='function _cct(){ claude "$@"; }; _cct'
# Navigate to your projects directory and start Claude Code
alias ccproject="cd ~/projects && claude"Reload after adding aliases:
source ~/.zshrcCLAUDE.md Starting Template
Place this file in your project root as CLAUDE.md. Claude Code reads it at the start of every session, so your project context is always available without re-explaining it.
# Project: [Project Name]
## Stack
- Language: TypeScript / JavaScript
- Framework: [Next.js / Express / other]
- Package manager: npm
- Node version: 20 LTS
## Conventions
- [e.g. All async functions use async/await, not callbacks]
- [e.g. Component files use PascalCase]
- [e.g. API responses always include { data, error, status }]
## Key Commands
- Dev server: npm run dev
- Tests: npm test
- Lint: npm run lint
- Build: npm run build
## Do Not Modify
- [e.g. /src/generated — auto-generated files]See what CLAUDE.md does for a detailed explanation of how Claude Code uses this file and how to write effective context.
Common Mac Issues and Fixes
| Issue | Cause | Fix |
|---|---|---|
brew: command not found after install | Homebrew not in PATH | Add Homebrew to PATH as shown in installer output, then source ~/.zshrc |
nvm: command not found | nvm config block missing from .zshrc | Add the 3-line nvm block to ~/.zshrc and run source ~/.zshrc |
claude: command not found after npm install | nvm bin directory not in PATH | Run nvm use 20 and retry; ensure nvm block is in .zshrc |
API key errors despite setting in .zshrc | VS Code terminal inheriting different shell | Open a new terminal window or run source ~/.zshrc inside the VS Code terminal |
| Permission denied on Homebrew directories | macOS Sequoia or later permission changes | Run brew doctor and follow any ownership fix instructions |
FAQ
Do I need Homebrew to install Claude Code on Mac?
No. Homebrew is the recommended path because it makes nvm installation straightforward, but you can install nvm directly from github.com/nvm-sh/nvm or install Node.js directly from nodejs.org.
The direct Node.js installer works but puts Node in a system directory, which can cause sudo-related issues with global npm installs.
Does Claude Code work on Apple Silicon (M1, M2, M3, M4)?
Yes. Claude Code is a Node.js application and runs natively on Apple Silicon. Node 20 LTS has full ARM64 support. No Rosetta 2 translation is needed.
Can I use Claude Code with multiple projects on the same Mac?
Yes. You run claude in any project directory and Claude Code reads the context of that directory. Each project can have its own CLAUDE.md with project-specific conventions. There is no per-project installation needed.
How do I update Claude Code after a new version releases?
Run the same install command with the -g flag:
npm install -g @anthropic-ai/claude-codenpm will update the global package to the latest version. Check the current installed version at any time with claude --version.
Ready to get your Mac set up for Claude Code?
You now have everything you need: Homebrew, nvm, Node 20 LTS, the Claude Code install, and a CLAUDE.md template to make every session productive from the start. The setup takes under 30 minutes on a clean Mac.
Path one: set it up yourself. Follow the steps in this guide in order and use the troubleshooting table if anything goes sideways. Once your environment is running, the Claude Code course is the fastest way to become productive with the tool.
Path two: work with Phos AI Labs. If your engineering team is rolling out Claude Code at scale and you want consistent configuration, CLAUDE.md standards, and team onboarding patterns that reduce ramp-up time, Phos AI Labs is a CCA-F certified Claude implementation partner that handles that process. Thirty minutes, no deck. Start here.