Claude Code on the Mac

There is no AI here. All content is human-authored and tested for accuracy.

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.

I recommend using our free app to install Claude Code and configure updates. It is a FREE Mac app that installs Claude Code, configures your system, and verifies it is working. It does everything this guide covers, but easier and faster. 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.

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.

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.