claude update Command | When to Use Automatic vs. Manual Updates

Basic Behavior of the claude update Command

claude update is a command that lets you manually pull in the latest version right now, without waiting for the background auto-updater (source: Claude Code official documentation).

claude update

When you run this command, Claude Code's built-in updater downloads and replaces the binary with the latest version. It works for both the native installer and npm installation paths, but claude update does not function as an update mechanism if you installed via Homebrew, WinGet, apt, dnf, or apk. You'll need the appropriate package manager command for those (details below).

After updating, you can verify the version with:

claude --version

Update Methods by Installation Path

First, confirm which method you used to install Claude Code.

Only the native installer supports automatic updates. All other installation methods require manual updates.

Native Installer — Auto-Updates Enabled by Default, claude update for Immediate Updates

When installed via the native installer, Claude Code checks for updates at launch and periodically while running. Downloads and installation happen in the background, and the new version takes effect on the next launch.

The install command for macOS / Linux / WSL is:

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

The install command for Windows PowerShell is:

irm https://claude.ai/install.ps1 | iex

Both are designed so that the next launch brings the latest version, so you don't need to do anything if you're not in a hurry. Only run claude update when you need the update applied immediately.

Run claude doctor to check the result of the most recent auto-update and view detailed installation status.

claude doctor

Homebrew (macOS) — brew upgrade and Opting In to Auto-Updates

Homebrew installations have auto-updates off, so you need to update manually.

# If you installed the stable channel cask
brew upgrade claude-code

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

The difference between the two casks is:

• claude-code (stable): Approximately one week behind, skips releases with critical bugs
• claude-code@latest (latest): Delivered on the day of release

To enable auto-updates, add CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE to your settings file.

{
  "env": {
    "CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE": "1"
  }
}

Once configured, Claude Code will run brew upgrade in the background when a new version is available and prompt you to restart when complete. Run brew cleanup periodically to reclaim disk space from older versions.

WinGet (Windows) — winget upgrade and Opting In to Auto-Updates

WinGet installations also have auto-updates off by default.

winget upgrade Anthropic.ClaudeCode

Just like Homebrew, setting CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE to 1 enables auto-updates. However, if Claude Code is running, Windows may lock the binary and cause the upgrade to fail. If this happens, quit Claude Code and try again.

npm — Do Not Use npm update -g

The most important point for npm installations is that npm update -g may not upgrade to the latest version. The official documentation explicitly states that npm update -g "respects the semver range from the time of installation and may not upgrade to the latest release."

Always use the following command to update:

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

If an old binary remains and causes unstable behavior, a clean reinstall is effective:

1. Remove the existing package: npm uninstall -g @anthropic-ai/claude-code
2. Install the latest version: npm install -g @anthropic-ai/claude-code@latest
3. Verify the version: claude --version

Using sudo npm install -g can cause permission and security issues. If you encounter permission errors, the official recommendation is to review your npm prefix configuration.

Linux Package Manager (apt / dnf / apk)

Claude Code installed via apt, dnf, or apk does not auto-update. Update it through the system's normal upgrade flow.

# Debian / Ubuntu (apt)
sudo apt update && sudo apt upgrade claude-code

# Fedora / RHEL (dnf)
sudo dnf upgrade claude-code

# Alpine Linux (apk)
apk update && apk upgrade claude-code

Because administrator privileges are required, these are not covered by CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE. Claude Code may show a notification before a new version is available in the package manager. If the upgrade fails in this case, wait a few hours and try again.

Choosing a Release Channel — latest vs. stable

The autoUpdatesChannel setting lets you balance speed and stability.

Change the setting via the "Auto-update channel" option in the /config command, or write it directly to settings.json.

{
  "autoUpdatesChannel": "stable"
}

Switching from "latest" to "stable" may result in a downgrade to an older version. If this happens, choosing "Stay on current version" will automatically set minimumVersion to prevent rolling back to an older version after the switch.

Version Pinning — minimumVersion and DISABLE_AUTOUPDATER

To prevent downgrades below a specific version, set minimumVersion.

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.100"
}

To completely disable auto-updates, use DISABLE_AUTOUPDATER.

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

DISABLE_AUTOUPDATER only stops background checks — the claude update command still works. To block all updates including manual ones via claude update, set DISABLE_UPDATES. This is useful when you want to manage a pinned version, such as when distributing binaries within your organization.

Diagnosing Update Status with claude doctor

When you're unsure whether updates are working correctly, claude doctor provides a comprehensive check. It diagnoses your installation status, version, the result of the most recent auto-update attempt, and any configuration issues.

claude doctor

If you see "Auto-updates: enabled, last check succeeded", auto-updates are working normally. If you don't have write permissions to the global directory for the npm version, claude doctor will guide you through the specific fix.

Installing a Specific Version

The native installer supports installing a specific version by number.

# macOS / Linux (specify version)
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89

# Specify the stable channel
curl -fsSL https://claude.ai/install.sh | bash -s stable

On Windows PowerShell:

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.89

The channel you select at install time becomes the default channel for auto-updates.

Frequently Asked Questions

Q. I ran claude update but my version is still old.

If you installed via Homebrew, WinGet, or apt, claude update will not work. Use the upgrade command for your respective package manager. Even with the native version, changes take effect on the next launch, not immediately.

Q. I accidentally ran npm update -g on the npm version.

Simply run npm install -g @anthropic-ai/claude-code@latest to overwrite it.

Q. I received a notification about an auto-update but couldn't update via Homebrew.

Distribution to the package manager may be delayed. Try again after a few hours.

claude update is a convenient command for immediate updates, but it doesn't work for every installation method. The surest path to a successful update is to first confirm your installation method and use the corresponding update command. For macOS-specific procedures, see the Claude Mac update article; for Linux-specific procedures, see the Linux update detail article.