Claude Mac Update | Auto-Update, brew, and npm Procedures

Three Mac Update Paths — Auto-Update Availability Determines Your Workflow

Claude Code on Mac can be installed via native installer, Homebrew, or npm, and each has a different update mechanism source. The native installer runs background auto-updates, so developers always have the latest version without having to think about it. Homebrew and npm require manual updates, which means you can easily fall behind if you leave things alone for a few weeks after a release.

The decision of which path to choose is straightforward: use native if you want the whole team on the latest version at all times, brew if you want to fit into an existing Homebrew-centric dev environment, and npm if you want PATH management as part of a Node.js project. For new installations, the auto-update advantage makes the native path the top recommendation.

Note that this article focuses on Claude Code. The separate Claude Desktop App for Mac is distributed as a dmg or via the App Store, and is updated through "Check for Updates" in the app menu or through the App Store — it uses a GUI workflow rather than CLI commands, which is covered in a later section.

Native Installer — The Most Recommended Path with Background Auto-Updates

The native installer is Anthropic's officially recommended path. Installation on Mac is completed with this single line source:

curl -fsSL https://claude.ai/install.sh | bash

Claude Code installed via this method periodically checks for new versions at launch and while running, downloading updates in the background when found. The new version actually takes effect at the next launch, so there is no risk of unexpected behavior changes mid-session. It supports both Apple Silicon and Intel Macs, with macOS 13.0 (Ventura) or later required.

claude update — The Universal Immediate-Update Command

If you don't want to wait for the background check and want to fetch the latest version right away, run the following in your terminal source:

claude update

This command works as a universal immediate-update command across all three paths — native, Homebrew, and npm. Use it when you want to try new features from release notes right away, or when you need an explicitly pinned version in a CI job.

Updating with Homebrew — brew upgrade and the Auto-Update Flag

If you installed via Homebrew, auto-updates do not run by default. Manual updates are performed with the following commands source:

# If installed via the stable cask
brew upgrade claude-code

# If installed via the latest cask
brew upgrade claude-code@latest

Note that the cask name depends on which one you chose during installation. The stable cask is the stable release channel, while latest gives you the newest features immediately.

Automating Homebrew Updates with CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE

For teams that want auto-updates even with Homebrew, Anthropic provides automatic upgrades via an environment flag source. Adding the following to your settings.json causes Claude Code itself to periodically run brew upgrade in the background:

{
  "CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE": "1"
}

This flag is the practical solution for teams that want to stay close to automatic without switching to the native installer. Note that Homebrew's own brew update is a separate command that updates Formula metadata — you need upgrade to actually update Claude Code.

Updating with npm — Avoid sudo and Always Specify latest

If you installed via npm install -g in a Node.js environment, the update command is source:

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

One important caution explicitly noted in the official documentation: npm update -g may not advance to the latest version. Due to npm's semver resolution behavior, it tends to stay on the latest patch of the current version, so you should always use npm install with @latest.

Never Use sudo npm install -g

When you encounter permission errors, the temptation is to add sudo, but the official Claude Code documentation prohibits sudo npm install -g for security and permission reasons source. Instead, the correct approach is to switch Node.js's prefix to $HOME/.npm-global, or switch to a user-space Node installation via nvm and then install globally. If you are using zsh on Mac as-is, simply adding export PATH="$HOME/.npm-global/bin:$PATH" to your ~/.zshrc and reloading it will do the trick.

Release Channel Switching — Choosing Between latest and stable

With the native path, you can switch the update cadence between two modes using the autoUpdatesChannel setting source:

{
  "autoUpdatesChannel": "stable"
}

The available values are:

1. latest (default): New features arrive immediately after release — the aggressive setting for developers.
2. stable: Delivered about one week later, with versions that had major regressions skipped — the conservative setting for production use.

Individual developers who want to try new features early should stay on latest, while client projects or educational environments where multiple people need to be on the same version should switch to stable. You can also make this switch through the /config menu without touching the settings file directly.

Post-Update Verification — claude --version and claude doctor

The standard way to confirm that an update has taken effect is a two-step process source:

claude --version
claude doctor

claude --version returns the version number of the currently running Claude Code. If it matches the release notes, the update was successful. claude doctor inspects the state of all dependencies (ripgrep, Node, login session, notification permissions, etc.) in one shot — use it as the first step in diagnosing any unexpected behavior after an update.

Whether you need to reopen your terminal for the update to take effect depends on your installation path. With the native installer, the new version takes effect the next time you run claude, so exit and restart your session. With Homebrew or npm manual updates, the new binary is active as soon as the command completes.

Common Update Troubleshooting — Permissions, PATH, and Cache

Here are three common sticking points when updating on Mac:

1. brew or npm stops due to permission errors: This is often caused by broken ownership under ~/Library or /usr/local, which can be fixed with sudo chown -R $(whoami). If you are on Apple Silicon, Homebrew lives under /opt/homebrew, so check ownership there as well.
2. An old claude binary remains in PATH: If which claude returns multiple paths, compare the output of brew list claude-code and which -a claude, then remove the unwanted one and reinstall.
3. Cache still shows the old version number: The zsh function hash cache may be stale, which you can clear with hash -r. If the version still does not change, reopen your terminal.

Since claude doctor detects most of these issues at once, the fastest diagnostic order is claude doctor first, then PATH and ownership.

Updating Claude Desktop App for Mac — Menu and App Store

Separate from the terminal-based Claude Code, if you use the GUI Claude Desktop App for Mac, the update path is different. For the version installed by downloading a dmg from the official Anthropic website, you can check for the latest version by selecting "Claude" → "Check for Updates..." from the app's menu bar.

If you installed via the App Store, update through the App Store's "Updates" tab. The App Store version has some behavioral differences due to sandbox constraints, and the version from the official website is often recommended for developers source.

The login account is shared between the CLI and GUI versions, so signing in to Pro or Max on one will automatically carry authentication over to the other. As long as you remember that updates are managed per app, running both versions on Mac simultaneously presents no operational issues.

Summary — The Key Decision for Keeping Claude Up to Date on Mac

Keeping Claude up to date on Mac is 90% solved the moment you choose the native installer. Background auto-updates work out of the box, and you just toggle between aggressive and conservative modes with autoUpdatesChannel — that is all you need to manage. If you choose Homebrew or npm, the golden rule is to align with the officially recommended approach using CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 or @latest.

For post-update verification, claude --version and claude doctor together cover nearly everything. To avoid the mistake of thinking it worked while actually still being on the old version, always compare the version number from the release notes against your local output. For the initial installation on Mac, also refer to the companion article Claude Code Mac Introduction to cover the full flow from installation to updates.