November 17, 2026 · 3 min read
Why Your Claude Code Isn't Updating (and How to Fix It)
Stop guessing why your Claude Code isn't updating. Native scripts auto-update, but Homebrew, WinGet, and npm installs fail silently without config.
Native script installs of Claude Code update themselves quietly in the background, but if you installed via Homebrew, WinGet, or npm, your tool is silently stuck on an old version until you configure it or run a manual command.
If you've been wondering why new features aren't showing up or why your syntax keeps lagging behind the docs, your package manager is almost certainly eating your updates. Keeping your AI coding assistant maintenance routine from breaking your local environment requires understanding how these different install paths actually behave.
Check your install health before running blind commands
Don't guess why an update failed—run claude doctor immediately to inspect settings files, version mismatches, and the exact error code from your last background update attempt.
Running claude --version only tells you what's currently executing in your shell, which prints something like 2.1.211 (Claude Code). It won't tell you if your npm global directory has permission locks or if you've accidentally spawned a conflicting second installation. claude doctor is entirely read-only, meaning it won't spin up a session or modify your workspace. It's the single best diagnostic step when an update hangs. If you're managing complex visual bugs across multiple environments alongside your CLI tools, capturing exact DOM states with markagent keeps your prompt context aligned with what's actually rendered on screen.
Target the right update command for your install method
Homebrew and WinGet installations never auto-update by default, meaning you have to manually invoke upgrades or explicitly opt into background management via environment variables.
Here is what your upgrade path looks like depending on how you originally pulled the binary:
- Native Script: Runs automatically, but
claude updateforces an immediate pull. - Homebrew: Requires
brew upgrade claude-code(orbrew upgrade claude-code@latestif you track the bleeding-edge cask). - WinGet: Requires
winget upgrade Anthropic.ClaudeCodeafter closing any active terminal windows to release file locks. - npm: Requires an explicit
@latesttag (npm install -g @anthropic-ai/claude-code@latest) to bypass strict semver range locks.
If you want Homebrew and WinGet to stop ignoring background updates, set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 in your environment. Otherwise, your system package manager will sit quietly while the codebase evolves past you.
Switch to the stable release channel if you hate Monday morning regressions
Set your autoUpdatesChannel to stable in your configuration file if you can't afford broken dependencies every time Anthropic pushes a patch.
{ "autoUpdatesChannel": "stable" }
The default latest channel feeds you features the second they compile, which occasionally introduces regressions that break local workflows. The stable channel lags roughly a week behind, filtering out the volatile builds. You can also pin a absolute version floor using minimumVersion if you're managing strict team environments where drift causes CI failures.
Fix the silent culprits when updates refuse to take
Two hidden configurations—custom symlinks and conflicting global binaries—account for almost every failed update attempt.
If you previously set up a custom launcher script at ~/.local/bin/claude, your system will successfully download new versions in the background while your legacy script intercepts execution and forces the old binary to run. Delete that custom symlink and let claude update rebuild the pointer.
Never use sudo npm install -g to fix write permissions on global directories. You'll introduce root-owned file permission blocks that will permanently break future automated updates. Fix your npm prefix instead.
Lock down update behavior for enterprise or offline stability
Disable background checks completely by injecting DISABLE_AUTOUPDATER=1 into your environment variables if your build pipeline requires absolute version determinism.
{
"env": {
"DISABLE_AUTOUPDATER": "1"
}
}
This stops background checks cold while still letting you manually run claude update when your team explicitly greenlights a version bump. If you need to lock the tool down so hard that even manual updates fail—common in tightly audited enterprise deployments—use DISABLE_UPDATES instead. Stop letting silent environment drift break your AI coding assistant maintenance. Pin your versions, fix your package manager flags, and keep your CLI current.