Claude Code on Mac

Expert guide to installing Claude Code on macOS. All the prerequisites for coding. How to install the Claude Code CLI, update, and fix errors and problems. Compare Claude Desktop.

Claude Code, from Anthropic, is the most popular AI coding tool. Run it in your terminal with the claude command, and it reads your codebase, edits files (with your permission), and runs commands.

These Mac Install Guide tutorials cover installing and configuring Claude Code on a Mac: setting up the developer environment, installing the tool, keeping it updated, and fixing common problems.

I recommend using our free app to get Claude Code working on your Mac. It is a FREE Mac app that installs Claude Code and the developer tools it needs, configures your system, and verifies it is working. It does everything these guides cover, but easier and faster. Here are all the details about the app before you download. Then:

Download the app "Set Up Your Mac for Claude Code"

Getting Claude Code working is just a part of setting up your development environment. See a complete guide to set up a Mac for development.

Guide to the Claude Code guides

If you're not using our install app, read here to find what you need. To set up and install:

Set up your Mac first: What's Needed to Run Claude Code
Options to install the CLI tool: Install Claude Code on Mac
Install with Homebrew (recommended): Brew Install Claude Code
Compare CLI and GUI versions: Claude Code vs Claude Desktop

To maintain and troubleshoot:

Keep the coding tool current: Update Claude Code
Errors and fixes: command not found: claude

Claude Code is a tool that takes several forms

Claude Code is actually a coding tool that takes several forms, not a single app. The same tool can be used in the terminal CLI, editors such as Zed or VS Code or JetBrains, the Claude Desktop app's Code tab, and the web at claude.ai/code. Your CLAUDE.md guidance file, configuration settings, and MCP servers are shared across each version.

Developers who "live in the terminal" prefer the Claude Code CLI. Open a project folder, type claude, and the tool runs for you, proposing edits and running commands that you approve. To install the CLI, see Install Claude Code on Mac.

Developers who prefer an editor (such as Zed or VS Code or JetBrains) can access Claude Code with an agent panel and line-by-line code editing.

The Claude Desktop app is a graphical interface that provides a chat, cowork, and code tab. It combines Claude Code with AI chat and the Cowork general-purpose business AI agent. I recommend installing and using both the CLI and the Desktop app, seeing which you prefer.

Tell Claude Code apart from Claude Desktop

Claude Code and Claude Desktop are easy to confuse. Claude Code is the dedicated coding tool that can be used via the terminal, editor, or Claude Desktop. Claude Desktop is a desktop application with three tabs (Chat, Cowork, and Code), where the Code tab is Claude Code with a graphical interface. The practical question is whether you prefer to use the terminal CLI or the graphical app. If you prefer to keep your attention focused inside the terminal, use the Claude Code CLI. The Claude Desktop app is more full-featured, maintaining a list of past sessions, and providing a conversational interface with prompts and responses.

Claude Code vs Claude Desktop compares the CLI and GUI tools, shows which config files and MCP servers they share, and helps you choose.

Set up your Mac first

If your Mac is already set up for development, you can install Claude Code with one command. But real work needs a configured developer environment: a terminal application, Homebrew, the Xcode Command Line Tools, git, a code editor, and a paid Claude plan. If your Mac is not set up for development yet, start with our prerequisites setup guide or use our free app "Set Up Your Mac for Claude Code".

What's Needed to Run Claude Code walks through each piece, with a diagnosis so you find what is missing.

Install Claude Code

For developers, I recommend installing Claude Code with Homebrew: brew install --cask claude-code installs Claude Code alongside other Homebrew packages. Anthropic's native installer is the alternative if you do not use Homebrew, and it auto-updates in the background out of the box. There is also an npm method to install Claude Code but I don't recommend it.

Install Claude Code on Mac covers the recommended Homebrew install as well as the native-installer option, the first-run browser sign-in, and verification. Brew Install Claude Code goes into detail on the Homebrew install option: release channels, upgrading, auto-update, and uninstalling.

Claude Code payment and pricing

Claude Code requires a paid Claude plan (Pro, Max, Team, or Enterprise) or an Anthropic Console or Anthropic API account. The free Claude.ai plan that people use for AI chat does not include Claude Code. Sign in with your browser the first time you launch the tool. No password is typed into the terminal. Plan names and prices change, so check the current tiers at claude.com/pricing.

Currently the cheapest Anthropic plan is the Pro plan at USD $20/month. With heavy use, expect to hit usage limits (many developers end up paying $100/month for a Max plan). Claude is currently the most popular AI coding tool and Anthropic has a better company reputation than OpenAI, but OpenAI offers limited use of their Codex coding tool with their ChatGPT Go plan at USD $8 in the US (and cheaper in some other regions). With current models, Codex can be more efficient than Claude Code, and developers report hitting usage limits more often with Claude Code than Codex. So Codex can be cheaper but many people still prefer Claude Code if they can afford it.

Staying updated with Claude Code

You can configure the Homebrew install of Claude Code to auto-update. See Brew Install Claude Code.

The native installer version of Claude Code updates automatically in the background.

Update Claude Code shows how to force an update, upgrade a Homebrew or npm install, choose a release channel, and fix conflicting installs.

Troubleshoot Claude Code

The most common problem is zsh: command not found: claude, which means the install folder is not on your PATH. Other issues include a version that does not change after an update and an npm global install that cannot auto-update.

command not found: claude diagnoses the PATH problem and fixes it safely. For version problems, see the troubleshooting section of Update Claude Code.

Look up common commands and paths

Here are essential commands:

# Install Claude Code with Homebrew (recommended)
$ brew install --cask claude-code

# Install Claude Code (native installer)
$ curl -fsSL https://claude.ai/install.sh | bash

# Start Claude Code in your project
$ claude

# Check the version
$ claude --version

# Run the health check
$ claude doctor

# Force an update on a native install
$ claude update

# List every claude on your PATH (conflict check)
$ which -a claude

Key paths:

~/.local/bin/claude: the native installer's binary
~/.claude/ and ~/.claude.json: your Claude Code configuration
CLAUDE.md: per-project notes Claude Code reads at the start of each session
.mcp.json: per-project MCP server configuration

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.