Claude Code is one of those tools that sounds complicated until you actually set it up. If you have a Mac, the whole process takes about five minutes. Sometimes less.
This guide walks you through every step on how to install Claude Code on Mac. From checking requirements to running your first real command.
It also covers the post-install setup that makes Claude Code genuinely useful on your projects, and the common mistakes that waste people’s time.
What Is Claude Code?
Claude Code is a terminal-based AI coding tool built by Anthropic. It runs inside your Mac’s Terminal app and works directly with your project files. You type a command in plain English, and it reads your code, suggests edits, writes new files, runs tests, and handles Git operations for you.
It is not a chatbot you copy-paste code into. It actually sits inside your project folder, understands the full context of your codebase, and makes changes right there. You approve every edit before it gets applied. It can also run shell commands, manage branches, and even do multi-file refactors across your entire project.
There is an important distinction to make here. Claude Code is different from the Claude Desktop app and the Claude Code VS Code extension. The Desktop app is a regular chat interface for asking questions and pasting snippets. The VS Code extension adds a side panel inside your editor. Claude Code, the CLI version, runs entirely in Terminal. It is the most powerful of the three because it has full access to your file system and can execute commands directly.
What You Need Before Installing
Before you open Terminal and start typing commands, make sure your Mac checks these boxes:
- macOS 10.15 (Catalina) or newer. This covers most Macs from 2019 onward. Both Intel and Apple Silicon (M1 through M4) Macs are supported. Click the Apple menu, then “About This Mac” to check your version.
- A paid Claude account. The free plan does not include Claude Code. You need at least Claude Pro ($20/month), Claude Max ($100 or $200/month), a Team or Enterprise seat, or an Anthropic Console account with API credits.
- An internet connection. Claude Code sends requests to Anthropic’s servers, so it needs to be online to work.
- Terminal access. Every Mac comes with Terminal built in. Press Cmd + Space, type “Terminal,” and hit Return. If you prefer iTerm2, that works too.
A quick note on which Claude plan to pick. If you are just getting started, Pro at $20/month is enough for most individual developers. It gives you Claude Code access in the terminal, plus Claude on the web and desktop.
Max at $100/month (5x usage) or $200/month (20x usage) only makes sense if you are using Claude Code heavily throughout the day and hitting rate limits on Pro.
One more thing: if you plan to use the native installer (which is the recommended method), you do not need Node.js, Homebrew, or any other dependency. The installer handles everything on its own.
How to Install Claude Code on Mac
There are three ways to install Claude Code on a Mac. Each one works, but they suit different types of users. Here is a quick comparison before we get into the details:
Method | Dependencies | Auto-Updates | Best For |
|---|---|---|---|
Native Installer | None | Yes | Most users, beginners |
Homebrew | Homebrew | No (manual) | Developers who manage everything via brew |
npm | Node.js 18+ | No (manual) | Node.js developers who want version pinning |
Method 1: Native Installer (Recommended)
This is the fastest and cleanest way to install Claude Code. No dependencies, no package managers, nothing extra. Anthropic recommends this method for most Mac users, and it is easy to see why.
It downloads the binary, puts it in your PATH, and sets up automatic background updates. When a new version comes out, you do not have to do anything. It just updates itself.
Open Terminal on your Mac. You can find it inside the Applications folder on Mac under Utilities, or just press Cmd + Space and type “Terminal.”
Once Terminal is open, paste this command and press Return:
curl -fsSL https://claude.ai/install.sh | bash
The installer will run for about 30 to 60 seconds. It will ask you to pick a theme and show some security notes. Follow the prompts and you are done.
After the install finishes, verify everything is working by typing claude –version in Terminal. You should see a version number printed back. If you want an even deeper check, run claude doctor instead.
This runs a full diagnostic that checks your environment, authentication status, and configuration. Green checkmarks mean everything is good.
Method 2: Homebrew
If you already use Homebrew to manage tools on your Mac, this method keeps everything in one place. No extra scripts to run, no curl commands. It is a single command:
brew install –cask claude-code
That is it. The “claude” command will be available from any folder immediately.
There are a couple of things worth knowing here. Homebrew offers two casks for Claude Code:
- claude-code tracks the stable release channel. It is usually about a week behind the latest version and skips builds with known bugs.
- claude-code@latest tracks the newest builds as soon as they ship.
For most people, claude-code (the stable channel) is the right pick. And one important caveat: Homebrew does not auto-update Claude Code. You need to run brew upgrade claude-code manually whenever you want the latest version.
Method 3: npm (Legacy)
This method still works, but it is no longer the recommended approach. Use it only if you are already deep into Node.js tooling and want your global packages managed together, or if you need to pin a specific Claude Code version for a CI pipeline.
You will need Node.js version 18 or higher installed on your Mac. Check your version first by running node –version in Terminal.
If you are on Node 18+, install Claude Code with:
npm install -g @anthropic-ai/claude-code
If you get a permission error that says something like “EACCES: permission denied,” do not reach for sudo. That creates more problems than it solves. Instead, fix your npm directory permissions by running these two commands:
mkdir ~/.npm-global
npm config set prefix ‘~/.npm-global’
Then add this line to your ~/.zshrc file:
export PATH=~/.npm-global/bin:$PATH
Restart your terminal and try the install command again. It should work without issues.
To update an npm installation later, run npm install -g @anthropic-ai/claude-code@latest. Do not use npm update -g, as it respects the semver range from the original install and might not actually give you the newest version.
How to Start Using Claude Code on Mac
Once Claude Code is installed, the first thing you need to do is authenticate. Type claude in your Terminal and press Return. A browser window will open asking you to log in with your Anthropic account (the one tied to your Pro, Max, or Team subscription).
Click “Authenticate” in the browser. Then come back to Terminal. Your credentials are stored locally, so you will not need to log in again unless you explicitly sign out.
If the browser does not open automatically, look for a long URL printed in the Terminal. Hold Cmd and click on it, or copy-paste it into your browser manually.
For headless setups or CI/CD environments where you cannot open a browser, you can set your API key as an environment variable instead:
export ANTHROPIC_API_KEY=sk-ant-your-key-here
Add that line to your ~/.zshrc to make it persistent across sessions.
Now, navigate to a project folder where you want Claude Code to work:
cd ~/your-project-folder
A quick shortcut: you can also right-click a folder in Finder, go to Services, and select “New Terminal at Folder.” This saves you from typing out the full path every time.
Type claude to start a session. You will see a prompt where you can type commands in plain English. Try something simple first:
- Explain what this file does
- Write unit tests for the main function
- Find and fix bugs in this file
- Add input validation to the signup form
Claude Code will read the relevant files, suggest changes, and show you a diff. You approve or reject each change before anything is written to disk. Nothing happens without your say-so.
You can also toggle Plan Mode by pressing Shift + Tab. In this mode, Claude Code plans out its approach before making changes. It is useful for bigger tasks where you want to see the strategy before any code gets touched.
One post-install set up a CLAUDE.md file. This is a markdown file in your project root that gives Claude persistent context about your project, like build commands, coding conventions, or architecture decisions. You can generate one automatically by typing /init inside a Claude Code session.
This analyses your codebase and creates a starter CLAUDE.md. It makes a real difference in how useful Claude Code is on your specific project. Without it, Claude has to guess your preferences. With it, Claude already knows things like your test framework, your preferred code style, and how to build the project.
Here are a few other handy commands to keep bookmarked:
Command | What It Does |
|---|---|
claude | Launch Claude Code |
claude –version | Check installed version |
claude doctor | Run diagnostics |
claude –continue | Resume your last session |
claude –resume | Pick from past sessions |
/init | Generate a CLAUDE.md for your project |
/help | View all available commands |
/exit | End your Claude Code session |
Shift + Tab | Toggle Plan Mode (Claude plans before acting) |
Common Mistakes to Avoid
Most Claude Code installation problems are self-inflicted. They come from skipping a step, using the wrong method, or following outdated advice from a 2024 blog post. Here are the ones that trip people up the most:
- “command not found: claude” after installing. This usually means your terminal has not picked up the new PATH yet. Close your Terminal window completely and open a fresh one. If it still does not work, check if the binary was installed properly by running “which claude” in Terminal.
For npm installs, you may need to add the npm global bin directory to your ~/.zshrc file manually. You can find the right path by running “npm config get prefix” and appending /bin to it.
- Using sudo with npm install. Never run “sudo npm install -g.” It installs packages as root, which creates cascading permission problems for every future global npm install. Fix your npm directory permissions instead (see Method 3 above).
- Trying to use Claude Code on the free plan. Claude Code is not available on the free Claude.ai plan. You need at least Claude Pro ($20/month) or API credits. If you try to authenticate without a paid account, it simply will not work.
- Having an old ANTHROPIC_API_KEY set in your shell. If this environment variable exists in your ~/.zshrc or ~/.bash_profile, Claude Code will silently use API billing instead of your Pro or Max subscription. You could end up paying per-token while your subscription sits unused. Check with “echo $ANTHROPIC_API_KEY” and remove it if you want to use your subscription.
- Skipping the CLAUDE.md setup. Claude Code works without it, but it works much better with it. Running /init takes a few seconds and gives Claude the context it needs to understand your project structure, coding style, and build process. Most people skip this and then wonder why the output feels generic.
- Expecting Homebrew to auto-update. Unlike the native installer, Homebrew does not update Claude Code in the background. You need to run “brew upgrade claude-code” yourself. If you forget, you might end up running a version that is weeks behind and missing recent fixes or features.
- Running Claude Code outside a project folder. Claude Code works best when you launch it from inside a project directory. Running it from your home folder or desktop gives it no useful context. Always navigate into your project first, then type “claude.”