Installing Claude Code on a Mac and what to check before the first session

Installing Claude Code on a Mac is one line in the terminal, and for most people it works the first time. The problems come just after: a command not found in a new terminal window, a second copy installed by a different method that runs instead of the first, an install that quietly stops updating, or a first session started in the wrong folder. Each of these takes minutes to fix and longer to diagnose if nobody mentioned it.

This guide covers the install itself briefly and spends more time on the choices and checks around it. The facts come from the Claude Code documentation at code.claude.com as of September 2026. Version numbers and defaults change often, so anything version specific should be checked against the documentation before relying on it.

What the Mac needs

The documented requirements for the command line version on macOS are short:

• macOS 13.0 or later
• 4 GB of RAM or more
• An Intel (x64) or Apple Silicon (ARM64) processor
• An internet connection
• Bash or Zsh as the shell; Zsh is the default on current macOS
• A location in a country Anthropic supports

An account matters as much as the machine. Claude Code requires a Pro, Max, Team or Enterprise subscription, or a Claude Console account with prepaid API credits. The documentation states that the free claude.ai plan does not include Claude Code. Organizations can also route it through Amazon Bedrock, Google Cloud or Microsoft Foundry.

Nothing else needs to be installed first. The native installer brings its own binary, and ripgrep, which Claude Code uses for searching files, is usually included. Git is not strictly required to run Claude Code, but most of what makes it safe to use, such as reviewing changes and undoing them, depends on the project being in a Git repository. Running git --version in Terminal confirms it is present; most Macs include it.

Choosing an install method

There are three ways to install the command line version on a Mac, and the difference that matters most is how each one updates.

Method	Command	Updates
Native installer (recommended)	curl -fsSL https://claude.ai/install.sh | bash	Automatic, in the background
Homebrew, stable channel	brew install --cask claude-code	Manual, with brew upgrade claude-code
Homebrew, latest channel	brew install --cask claude-code@latest	Manual, with brew upgrade claude-code@latest
npm	npm install -g @anthropic-ai/claude-code	Automatic when the npm directory is writable

The native installer is the documentation's recommendation. It places a launcher at ~/.local/bin/claude that points into ~/.local/share/claude/versions/, checks for updates on startup and while running, and applies them the next time Claude Code starts. The release channel can be set to latest, the default, or stable, which is typically about a week behind and skips releases with major regressions.

Homebrew suits people who manage every tool through it. The two casks map to the two channels. Homebrew installs do not update themselves by default; setting the environment variable CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE to 1 lets Claude Code run the upgrade in the background. Homebrew also keeps old versions on disk, so brew cleanup reclaims space from time to time.

npm installs the same native binary through a platform specific package. As of version 2.1.198 the package requires Node.js 22 or later. The documentation warns against sudo npm install -g because of permission and security problems, and recommends npm install -g @anthropic-ai/claude-code@latest over npm update -g for upgrades.

Picking one method and sticking with it avoids the most confusing problem on a Mac: two installations, with the older one earlier on the PATH, so updates seem to have no effect.

The desktop app is a separate option. Claude Desktop includes Claude Code in its Code tab and needs no terminal at all. It does not install the claude command. Anyone who wants both installs both.

Fixing command not found

The most common first problem is command not found: claude right after a successful install. The native installer puts the binary at ~/.local/bin/claude, and on some Macs that directory is not on the PATH.

The documented fix for Zsh is to add it to the shell profile and reload it:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Opening a new terminal window afterwards confirms the change persists.

Two related cases come up often. If only the VS Code extension was installed, there is no ~/.local/bin/claude at all: the extension bundles a private copy for its own panel and does not add it to the PATH. And if claude still runs after an uninstall, or runs an old version after an update, there is probably a second installation. The documentation lists three places a claude binary can come from: ~/.local/bin/claude for the native installer, ~/.claude/local/ for a legacy local npm install from older versions, and the global npm directory. Running which -a claude shows every copy on the PATH and which one wins.

Checks before the first session

Once claude runs, a few checks take less than five minutes and prevent most early confusion.

Version and health. claude --version prints a version number followed by "(Claude Code)". claude doctor prints read only diagnostics without starting a session: install health, the result of the last update attempt, settings file errors, and warnings with suggested fixes.

Login. Running claude the first time opens a browser to sign in. If the ANTHROPIC_API_KEY environment variable is set, Claude Code asks to approve the key instead. This catches people who set the variable for another tool and end up billed through the API rather than their subscription. /login switches accounts later.

Terminal setup. In Apple Terminal, the first run offers to configure the terminal. Accepting enables Option as the Meta key, which some shortcuts need, and turns off the audible bell for that profile. In iTerm2, the equivalent is setting the Option keys to "Esc+" in the profile. Shift+Enter for a new line works without setup in Apple Terminal, iTerm2, Ghostty, Kitty, WezTerm and Warp.

Notifications. Desktop notifications when a session finishes or waits for approval are sent by default in Ghostty, Kitty and iTerm2. In Apple Terminal, setting preferredNotifChannel to "terminal_bell" in ~/.claude/settings.json gives an audible alert instead.

Folder permissions. macOS protects Desktop, Documents and Downloads. The first time a session reads there, macOS may ask to grant the terminal access. Declining leads to "Operation not permitted" errors later that look like a Claude Code problem but are a system setting.

Where to start the first session

The first session should start in a real project, at its root. Claude Code works on the directory it was launched in, and the prompt shows that directory, the model and the version above the input. Starting in the home folder gives it access to everything in it and no project instructions to read.

A small repository that is already understood well is the best first choice, since it makes it easy to tell whether answers are right. The documentation's quickstart begins with questions rather than tasks: what the project does, where the entry point is, how the folders are organized. Only after that does it move to a first change.

Before that first change, two things are worth knowing:

• Which permission mode is active. On Pro, Max and Team plans, interactive terminal sessions start in auto mode, where a classifier reviews actions instead of asking. On other plans they start in Manual mode, which asks before edits and commands. Shift+Tab cycles modes, and the status bar shows the current one.
• How to undo. /rewind, or Esc pressed twice on an empty prompt, restores earlier checkpoints. It covers edits made with Claude's file tools, not changes made by shell commands, so a clean Git commit before the first task is the dependable safety net.

It also helps to keep the project folder visible while the session runs. The terminal shows what Claude Code says it did; a folder window shows what actually changed on disk. Some people run it inside a file manager with a built-in terminal so the two stay side by side. The features page shows that arrangement, and the FAQ covers requirements.

Problems that show up in the first week

A few issues appear often enough on a Mac to be worth recognizing on sight rather than diagnosing from scratch.

The version never changes. Two installations are the usual cause. which -a claude lists every copy the shell can reach, and the one printed first is the one that runs. Removing the older one, then running claude doctor, settles it. Homebrew installs also sit still until upgraded, so a version that stays the same for weeks is expected there rather than broken.

Option shortcuts do nothing. Most Mac terminals do not send Option as a modifier until told to. In Apple Terminal the setting is "Use Option as Meta Key" under Settings, Profiles, Keyboard; in iTerm2 it is the Option keys set to "Esc+". Until then, shortcuts such as Option+P have no effect and look like missing features.

Searching a project fails. Claude Code uses ripgrep for search, which is normally bundled. When search errors appear, the documentation's search troubleshooting section covers the exception and how to point it at a system copy.

A session in a protected folder cannot read files. Desktop, Documents and Downloads are protected by macOS. If the terminal application was never granted access, reads there fail with "Operation not permitted". The fix is in System Settings, under Privacy and Security, for the terminal application in use, not in Claude Code.

A tool works in one place and not another. Environment differences explain most of these. A session started from a terminal inherits the full shell environment. The desktop app, launched from the Dock, reads PATH from the shell profile but not every variable exported there. Putting the variables a project needs into the env block of a settings file makes both behave the same.

Updating and removing it later

With the native installer, updates arrive on their own. claude update applies one immediately, and claude doctor reports the result of the most recent attempt. Setting DISABLE_AUTOUPDATER to "1" in the env block of the settings file stops background checks while still allowing manual updates.

Removing it depends on how it was installed. For the native installer, the documentation's commands delete the launcher at ~/.local/bin/claude and the version files under ~/.local/share/claude. For Homebrew, brew uninstall --cask claude-code, or the @latest variant. Settings and memory in ~/.claude are separate and remain unless deleted too, which is useful when reinstalling by a different method.

What to change first

Install with the native installer unless every other tool on the Mac is managed by Homebrew, and run which -a claude once to confirm there is only one copy. Then run claude doctor, start the first session at the root of a small Git repository, and commit before the first change. To keep that folder in view while the session works, Atriens puts the terminal and the folder in one window.