Claude Code on the Mac

Written & tested for accuracy by a developer (not AI) · Updated June 2026

Update Claude Code

Update Claude Code on Mac. Upgrade Claude Code versions. How to force a claude update, upgrade a native, Homebrew, or npm install, and fix versions.

Claude Code is an AI coding tool that runs in your terminal with the claude command. It reads your codebase, edits files (with your permission), and runs commands so you can develop software with AI assistance.

How you update Claude Code depends on how you installed it: a native install updates itself in the background, while a Homebrew or npm install is one you update yourself. The next section breaks down each.

This page covers the Claude Code CLI, not the Claude Desktop app. If you are not sure which one you have, read Claude Code vs Claude Desktop first.

What to do now

Use my app to get more from Claude Code. It is a FREE Mac app that checks your Claude Code setup, adds the skills, MCP servers, and starter project you choose, and verifies Claude Code is working. Here are all the details about the app before you download. Then:

Keeping your developer tools current is one step in setting up your Mac. See the full Mac setup roadmap.

How updates work for each install method

How you update depends on how you installed Claude Code.

Installation with the native installer auto-updates in the background. Claude Code checks for a new version on startup, downloads and installs it in the background, and the update takes effect the next time you start Claude Code. You usually run no command at all.

A Homebrew install, the method most developers use, does not auto-update unless you configure it. You run brew upgrade --cask claude-code yourself, or add export CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 to your shell profile (~/.zprofile) so Claude Code runs the Homebrew upgrade for you. The release channels, the auto-update flag, and uninstalling are explained in detail on the page Brew Install Claude Code.

An npm install also requires manual updates. I do not recommend installing Claude Code with npm, but the steps below cover updating it if you have it.

If you are not sure which install you have, the section below shows how to find out with which -a claude.

Check Claude Code version

Before updating, see what you are running. Check the version:

$ claude --version

This shows a version string. To see which install, or installs, you have, list every claude on your PATH:

$ which -a claude

A single line is what you want. More than one line means conflicting installs, the usual reason a version looks stuck after an update. See "Fix a version that does not change," below.

Update a native install

A native install updates itself in the background, but you can force an update on demand:

$ claude update

Claude Code checks the release channel and either downloads and applies a newer version or reports that you are already up to date. Then confirm the new version:

$ claude --version

This displays a version string. If it still shows the old version, see "Fix a version that does not change," below. That is the most common update problem, and it is almost always conflicting installs rather than a failed download. For a deeper diagnostic, run the built-in health check:

$ claude doctor

This reports installation and configuration health, including the result of the last update attempt. Use it when claude update seems to have done nothing.

Update a Homebrew install

A Homebrew install does not auto-update, so you upgrade the cask yourself:

$ brew upgrade --cask claude-code

Homebrew upgrades the claude-code cask, or reports that it is already current. If you installed the latest-channel cask instead, upgrade that one:

$ brew upgrade --cask claude-code@latest

To make a Homebrew install update itself like the native one, set the auto-update flag described at Brew Install Claude Code.

Update an npm install

I do not recommend installing Claude Code with npm: it requires Node.js and pulls the tool through the npm registry, which adds a dependency and supply-chain risk you do not need. The Homebrew cask or the native installer is the better choice, so consider switching with Install Claude Code on Mac. If you already have an npm install, update it by reinstalling at the latest version. Do not use npm update -g, which respects the original version range and may not move you forward:

$ npm install -g @anthropic-ai/claude-code@latest

This installs the newest published version globally. Never run it with sudo, because a global npm install with sudo is a permission and security risk.

Choose an update channel and pin a version

These optional controls live in your Claude Code user settings file, ~/.claude/settings.json, which you edit by using the slash command /config when Claude Code is running.

  • Set the release channel with autoUpdatesChannel in ~/.claude/settings.json. The value latest is the default; stable runs roughly a week behind, skipping releases with major regressions. The friendly way to change it is /config, then Auto-update channel.
  • Pin a floor with minimumVersion. Claude Code refuses to run a version below the floor you set, so a background update can move you forward but never silently downgrade you.
  • Turn off background updates with DISABLE_AUTOUPDATER: "1" in the env block of ~/.claude/settings.json. Background updates stop, but a manual claude update still works. To block every update path, including manual, use DISABLE_UPDATES instead.

Troubleshooting

Before you change anything, find out what you are running and where it came from.

Fix a version that does not change

This is a common problem, and the usual cause is conflicting installations: more than one copy of Claude Code on your PATH, so the shell keeps launching an old one while a different copy updates. Work through these steps in order.

First, see the version you are actually running, and note it down:

$ claude --version

Run the deeper check, which reports installation and configuration health and the last update result:

$ claude doctor

List every claude on your PATH:

$ which -a claude

One path per installed copy appears here. More than one line is the smoking gun: you have conflicting installs, and the first one wins.

Next, check the three places a binary can come from. Run all three and note which ones exist. A No such file or directory or empty result is not an error: it just means nothing is installed in that spot. Check the native install:

$ ls -la ~/.local/bin/claude

Check for a legacy local npm install from older Claude Code:

$ ls -la ~/.claude/local/

Check for an npm global install:

$ npm -g ls @anthropic-ai/claude-code 2>/dev/null

Now keep just one install and remove the others. For most developers, the Homebrew cask is the one to keep. Run only the removal lines for the copies you do not want. Remove an npm global install:

$ npm uninstall -g @anthropic-ai/claude-code

Remove the legacy local install. Check the path before you run this, because rm -rf deletes without asking:

$ rm -rf ~/.claude/local

Remove a native install:

$ rm -rf ~/.local/bin/claude

Remove a Homebrew install (use claude-code@latest if that is the cask you installed):

$ brew uninstall --cask claude-code

Open a new terminal window and re-check. With one install left, claude --version shows the current version and which -a claude shows a single path:

$ claude --version

Fix an old version right after installing or updating

If claude --version still reports the old version right after an update, your shell is likely still pointing at the old binary it cached. Quit and reopen your terminal application so it re-reads your PATH, then check again:

$ claude --version

If the version is still wrong, the cause is either conflicting installs (see above) or a PATH problem. command not found: claude covers the PATH fix for both Homebrew and native installs.

Update installed, restart to apply

The message "Update installed" with "Restart to apply" (or "Restart to update") means Claude Code has installed a new version, but the session you are in still runs the old one. The new version takes effect the next time you start Claude Code.

With a native install on a Pro, Max, or Ultra plan, type /restart in Claude Code. It restarts Claude Code and resumes the same session, so you lose nothing.

With a Homebrew install, or on another plan, quit Claude Code and start it again. Type /exit, then run:

$ claude --continue

This starts the new version and picks up your most recent conversation. To choose an older conversation instead, type /resume after Claude Code starts. A Homebrew install shows this message only if you set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE, which makes Claude Code run the Homebrew upgrade for you (see Brew Install Claude Code).

Homebrew says Claude Code is out of date

If Claude Code shows Update available! Run: brew upgrade claude-code, or brew outdated lists claude-code, a newer version is waiting in Homebrew. Homebrew does not update Claude Code on its own. First update Homebrew's list of packages, so it knows about the newest release:

$ brew update

Then upgrade the cask:

$ brew upgrade --cask claude-code

If Homebrew answers Error: Cask 'claude-code' is not installed, you have the other cask. Check which one you have:

$ brew list --cask | grep claude-code

The two casks follow different release channels. The claude-code cask gets the stable channel, which runs about a week behind and skips releases with major problems. The claude-code@latest cask gets each version as soon as Anthropic releases it. So the claude-code cask is often a version or two behind Anthropic's release notes. That is expected. To get new versions sooner, switch casks as described in Brew Install Claude Code.

Handle an update notice that arrives before the package is ready

Claude Code can occasionally tell you an update exists before your package manager has published it. If brew upgrade or the npm reinstall reports nothing new, that is expected. Wait a short while and retry. No special command is needed.

Opus 5.5 not showing in Claude Code

If you can't find Opus 5.5 in Claude Code, your Claude Code is older than version 2.1.280, the first version that runs it. Anthropic released Opus 5.5 on September 22, 2026. An older version that tries to use it shows an error that ends with "Run 'claude update', or update the Claude desktop app, then try again." Check your version:

$ claude --version

Update with the command for your install method, as shown above (claude update for a native install, brew upgrade --cask claude-code for Homebrew). Then start Claude Code and choose the model:

/model opus

The name opus always means the newest Opus model, so you don't need to type the full model name. Type /model on its own to choose from a list instead.

If you use Claude Code through your work account, an administrator can limit which models you can choose. A message that says a model "is restricted by your organization's settings" or "is not available" means the setting comes from your organization, and only your administrator can change it.

Fast mode error on Opus 4.8

Fast mode for Opus 4.8 ends on November 30, 2026. Fast mode runs a model up to 2.5 times faster at a higher price per token, and on a Claude plan it is paid for with usage credits. After that date, Claude Code returns an error for a fast-mode request on Opus 4.8 instead of running it at normal speed. You see the error if Opus 4.8 is still your model and fast mode is still on (a ↯ symbol appears in Claude Code while fast mode is on).

Choose one of two fixes. To keep fast mode, switch to Opus 5.5, which needs Claude Code 2.1.280 or newer:

/model opus

Fast mode stays on with the new model. To keep Opus 4.8 at normal speed, turn fast mode off:

/fast off

Fix an npm global install that cannot auto-update

An npm global install cannot auto-update when the npm global folder is not writable by your user. Claude Code shows a one-time notice about this at startup, and claude doctor lists the available fixes. The durable fix is to stop fighting npm global permissions and switch to the Homebrew cask, the method most developers use, or the native installer. Both avoid npm's global-write problem. Remove the npm global install:

$ npm uninstall -g @anthropic-ai/claude-code

Then reinstall with Homebrew, Brew Install Claude Code, or the native installer.

A clean claude doctor plus a single line from which -a claude is the all-clear: one install, on the right channel.

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.