The Complete Guide to Updating Claude Code by Install Method

Your Claude Code update method depends entirely on how you installed it.

If you are waiting for a background upgrade that never arrives, you likely used Homebrew or WinGet instead of the native installer. Native installs handle upgrades silently in the background, while package manager installs require manual intervention. Let's fix your upgrade workflow right now.

Forget relying on a single global command to keep your coding assistant current. Different package managers handle binaries differently, which breaks assumptions about automatic upgrades. When you're building complex frontend features with an AI agent, running an outdated CLI version means missing out on crucial bug fixes and tool use improvements.

Native and npm installs update themselves silently.

If you installed via the native shell script or pinned your global npm package to @latest, you don't need to touch anything. These methods poll for new releases on startup, download the delta in the background, and apply the swap the next time you spin up a session.

I've run native installs for months without typing a single upgrade command. The binary patches itself seamlessly. If you prefer npm, make sure your target scope uses the explicit tag:

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

Avoid running a generic npm update -g. That command respects semver ranges in your global tree and often leaves you stranded on an older minor release while the team ships critical patches.

Package manager installs require explicit manual upgrades.

Homebrew, WinGet, and Linux package managers like apt or dnf will never auto-update your CLI tool. If you installed via these channels, your system treats the package just like any other CLI utility, meaning you own the upgrade cycle.

To pull the latest release on macOS via Homebrew, run:

brew upgrade claude-code

On Windows machines managed through WinGet, you'll need to trigger the package upgrade manually:

winget upgrade Anthropic.ClaudeCode

If you skip these commands, your local environment drifts out of sync with your team's shared prompts. When you're feeding complex UI bugs to your agent, running mismatched versions introduces weird tool execution errors that have nothing to do with your actual code.

Run claude doctor when your version looks frozen.

When an upgrade fails or your terminal insists you're running last month's build, skip the guesswork and run the diagnostics suite. The built-in claude doctor command inspects your global path, checks your config files, and reports the exact reason background updates are failing.

Common blockers include non-writable global npm directories or leftover shell aliases pointing to outdated binaries in /usr/local/bin. Once you diagnose the path conflict, you can force an immediate override using the manual CLI flag:

claude update

This bypasses the background check interval and forces the binary to fetch the latest production payload immediately.

Control your release channel and auto-updates in settings.

You aren't forced to live on the bleeding edge if your production workflow demands stability. You can explicitly configure your upgrade cadence by editing your global configuration file at ~/.claude/settings.json.

Add the channel parameter to pin your environment:

{
  "autoUpdatesChannel": "stable"
}

Switching to stable delays new releases by roughly a week, skipping major regressions before they hit your machine. If you want absolute control over your environment and hate background network requests, kill the background daemon entirely by exporting the DISABLE_AUTOUPDATER=1 environment variable in your shell profile.

Bridge your UI workflow directly to your agent.

Keeping your CLI updated is only half the battle; feeding precise visual context to your agent is where most workflows fall apart. When you're iterating on a dense React dashboard, typing out layout bugs wastes valuable tokens. Instead of writing paragraphs about broken margins, use markagent to click the exact DOM element, snap a cropped screenshot, and export a clean markdown prompt that drops straight into your terminal session.

Stop fighting your toolchain. Match your install method, lock in your release channel, and keep your coding agent fed with precise context.