The Story of How Switching Claude Code from Homebrew to Native Installation Made Things More Comfortable
Table of Contents
I ran brew upgrade claude-code on two Macs and got different installed versions. Mac mini got 2.1.73, MacBook Pro got 2.1.74. Same command, so why?
This "huh?" moment prompted me to switch my Claude Code installation method from Homebrew to native install. The short answer: it was worth switching. In this article, I'll address all the questions at once — why versions can differ, how to switch, and whether your settings and data will be lost.
Why Homebrew Can Cause Version Mismatches
After looking into it, it seems several factors are at play.
First, the Claude Code Homebrew cask is apparently designed to follow the stable release channel. The stable channel is delivered roughly one week behind latest, so there's a time lag between when Anthropic releases a new version and when it's reflected in the Homebrew cask definition. On top of that, since Homebrew 4.0, cask definitions are fetched from a JSON API via CDN, and differences in CDN edge node or local cache freshness can also have an impact. As a result, even if you run brew upgrade on two Macs at nearly the same time, you can end up with different cask definitions being fetched.
Furthermore, the official documentation states:
Homebrew installations do not auto-update. Run
brew upgrade claude-codeperiodically to get the latest features and security fixes. Known issue: Claude Code may notify you of updates before the new version is available in these package managers. If an upgrade fails, wait and try again later.
In other words, the Homebrew version doesn't auto-update — you need to run brew upgrade manually. And even when Claude Code itself notifies you that a new version is available, it may not have arrived in Homebrew yet. If you're working across multiple Macs, this mismatch becomes a subtle but persistent source of frustration.
Native Install Is Recommended
In the official documentation, the Native Install method is labeled "Recommended." The reason native install is recommended over Homebrew or WinGet is that auto-updates work.
The native install version periodically checks for updates in the background at startup and during execution, and automatically handles downloading and installing them. The next time you launch it, the new version is already in place.
Even when working across multiple Macs, each one will independently keep itself up to date, making it much less likely that you'll end up in a situation where "one machine is newer but the other is old."
How to Switch
Switching is very simple. Just uninstall the Homebrew version and run the native install.
1. Remove the Homebrew Version
brew uninstall --cask claude-code
2. Remove the npm Global Version If Installed
If you've installed it via npm in the past, remove that as well.
npm uninstall -g @anthropic-ai/claude-code
3. Run the Native Install
curl -fsSL https://claude.ai/install.sh | bash
4. Verify
claude --version
If a version number is displayed, you're done. It's also a good idea to run which -a claude to check that no stray claude binaries from other paths are left behind.
which -a claude
If the output shows only ~/.local/bin/claude, the switch is complete.
If You Get "command not found"
If claude --version returns command not found, ~/.local/bin may not be in your PATH. You can check with the following command:
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
If nothing is output, add the PATH to your .zshrc.
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Run claude --version again, and if a version number appears, you're good to go.
Will My Settings and Data Be Lost?
This is probably the biggest concern. The short answer: they normally won't be.
Claude Code's settings and state are stored separately from the executable.
~/.claude/settings.json— user settings~/.claude.json— global state including OAuth, themes, MCP servers, etc.- Per-project
.claude/and.mcp.json— project-specific settings
Neither brew uninstall --cask claude-code nor the native install will touch these files. Your login state, permission settings, and MCP server configuration will all remain intact.
The official documentation also notes that if you want to reset your settings, you need to explicitly delete ~/.claude and ~/.claude.json. In other words, if you don't delete them, they won't disappear.
If You Want to Back Up Just in Case
If you're worried, taking a backup before switching will give you peace of mind.
# Back up global settings
mkdir -p ~/claude-backup-$(date +%Y%m%d)
cp -R ~/.claude ~/.claude.json ~/claude-backup-$(date +%Y%m%d) 2>/dev/null
# Back up per-project settings (run in the project directory)
cp -R .claude .mcp.json ~/claude-backup-$(date +%Y%m%d)/ 2>/dev/null
How to Update the Native Version
The native install version is essentially auto-updating. It periodically checks for updates at startup and during execution, downloading and installing them in the background. Changes take effect on the next launch, so you normally don't need to do anything.
To Update Manually Right Now
claude update
Switching Release Channels
You can control how you receive updates by configuring the release channel.
"latest"(default) — receive new features immediately upon release"stable"— receive a stable version, typically about one week behind
To configure this, either select Auto-update channel from /config within Claude Code, or write it directly in settings.json.
{
"autoUpdatesChannel": "stable"
}
If you prioritize stability, "stable" is recommended.
If You Want to Disable Auto-Updates
Write the following in the env section of settings.json.
{
"env": {
"DISABLE_AUTOUPDATER": "1"
}
}
Verifying After an Update
claude --version
claude doctor
claude doctor is a command for detailed checks of your settings and state. It's also useful when something seems off.
Summary
The Homebrew version of Claude Code is easy to install, but since auto-updates don't work, version mismatches can occur across multiple machines depending on when you run manual updates.
Switching to native install largely eliminates this problem, since updates happen automatically in the background. (Updates take effect on the next launch, so there can be a temporary mismatch if machines are restarted at different times.)
- Switching is easy — 3 steps:
brew uninstall→ reinstall withcurl→ verify - Settings and data are preserved — config files are stored separately from the executable
- Auto-updates work — updates happen in the background, so you're always on the latest version
- Update frequency is adjustable via release channel — choose
"stable"if you prioritize stability
Since native install is also what the official documentation recommends, if you're still using Homebrew, now might be a good time to make the switch.