How to update Claude Code

How do you update Claude Code?

The right command depends on how you installed Claude Code. The official setup documentation lists one upgrade path per install method, and they are not interchangeable. If you are not sure which one you used, check the table below against where the claude command lives, or just run claude update and read what it prints.

Two details trip people up. For npm, the docs say to avoid npm update -g, because it respects the version range from your original install and may not move you to the newest release. And never use sudo with the npm install: Claude Code runs npm without sudo when it updates itself, so an install that needed sudo cannot update on its own.

After claude update runs, it reports Successfully updated from <old version> to version <new version> when something changed, or Claude Code is up to date when you were already current. Installs managed by Homebrew, WinGet or apk print Claude is up to date! instead. The update takes effect the next time you start Claude Code, so close the session and open a new one.

How do you check which version of Claude Code you have?

Run this in your shell, not inside a Claude Code session:

claude --version
claude doctor

The first command prints a version number followed by (Claude Code). The second, claude doctor, prints read-only diagnostics without starting a session: install health, settings-file validation errors, whether auto-updates are enabled, and the result of the last update attempt Claude Code recorded. Inside a session, /status opens the Status tab, which shows the version along with your model, account and connectivity.

If a version number matters for a feature, check before you assume. Claude Code's own documentation marks features with the version that introduced them, for example “requires v2.1.275 or later”. When a command from a tutorial does nothing on your machine, an old version is the first thing to rule out.

Does Claude Code update itself?

It depends on the install method. Native installations update automatically: Claude Code checks for updates on startup and periodically while running, downloads and installs them in the background, and the new version starts the next time you launch it. You do not have to do anything. If a background update fails, a short notice appears in the session footer, and you can keep working.

Homebrew, WinGet, apt, dnf and apk installs do not auto-update by default. For Homebrew and WinGet you can opt in by setting the environment variable CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE to 1. Claude Code then runs the upgrade in the background when a new version is available and shows a restart prompt on success. The upgrade targets only the Claude Code package. apt, dnf and apk always need a manual upgrade, because those commands need elevated privileges. WinGet can fail while Claude Code is running, because Windows locks the executable; Claude Code then shows you the manual command.

The docs flag one known issue for package managers: Claude Code may announce an update before the new version has reached the package manager. If the upgrade fails, wait and try again later. Homebrew also keeps old versions on disk after an upgrade, so run brew cleanup now and then to reclaim space.

What is the difference between the latest and stable channels?

Claude Code ships on two release channels. latest, the default, gives you new features as soon as they are released. stable serves a version that is typically about one week old and skips releases with major regressions. If you would rather wait a few days for other people to find the bugs, choose stable.

For the native installer and npm, set the channel in /config under Auto-update channel, or add it to settings.json:

{
  "autoUpdatesChannel": "stable"
}

Package managers pick a channel differently. With Homebrew, the cask name is the channel: claude-code tracks stable and claude-code@latest tracks latest. With apt, dnf and apk, the channel is the repository you add, and the setup docs show a stable and a latest URL for each. You can also choose at install time: the native installer accepts stable or latest as an argument, and the channel you pick then becomes your default for auto-updates.

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

# one exact version number
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89

The docs add a caveat. A newly launched model can require a Claude Code version newer than the stable channel serves. If a new model does not show up for you, move to the latest channel.

If you switch from latest to stable while already on a newer build, Claude Code prompts you either to stay on the current version or to allow the downgrade. Staying sets a minimumVersion floor in your settings. That setting makes background updates and claude update refuse any version below it:

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

How do you turn off Claude Code auto-updates?

Set DISABLE_AUTOUPDATER to "1" in the env block of your settings.json. This is useful when you want a fixed version for a project, or while you are in the middle of something and do not want the binary to change under you.

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

Confirm with claude doctor. On a native or npm install, the Auto-updates line should read disabled (set by env: DISABLE_AUTOUPDATER) instead of enabled.

That variable only stops the background check. claude update and claude install still work, which is what you want for a deliberate, manual update. To block every update path, manual ones included, set DISABLE_UPDATES instead. The docs recommend that for teams who distribute Claude Code through their own channels and need everyone on the version provided.

Where is the Claude Code changelog?

There are two official places, and neither needs a browser if you do not want one.

• In the terminal: run /release-notes inside a session. It opens an interactive version picker. Select one version to read its notes, or choose to show all versions. The notes appear in your transcript without entering the conversation Claude sees, so reading them does not use up context.
• On the web: the Claude Code changelog in the docs lists new features, improvements and bug fixes by version. The docs state that this page is generated from the CHANGELOG.md file in the anthropics/claude-code repository on GitHub.

Read the notes after an update that changes behavior you rely on, and before you switch to a new channel or pin a version. Release notes are also the quickest way to learn whether a bug you hit has already been fixed in a newer build.

If you build things that explain releases to other people, the board has an idea for exactly that: A changelog your users actually read. More tools for developers are in the developer tools category.

What if the update fails or the version does not change?

Work through these in order. Most failures come from one of four causes.

1. Run `claude update` yourself. If the session footer shows Auto-update failed · Run claude doctor, the troubleshooting guide says you can keep working without doing anything, and that claude update in your shell is the way to finish the update or to see the actual error.
2. Run `claude doctor`. It reports the last update attempt and flags problems with the install. On a native install it also reports a launcher that the native installer did not create.
3. Check for a custom launcher. On macOS and Linux the native installer manages ~/.local/bin/claude as a symlink into ~/.local/share/claude/versions/. If you replaced it with your own script, auto-update and claude update leave it in place, and your launcher decides which version runs. To hand control back, remove ~/.local/bin/claude and run claude update.
4. Check npm permissions. If an npm global install cannot update because the global directory is not writable, Claude Code shows a one-time notice at startup, and claude doctor lists the available fixes. Do not fix it with sudo.

If the error is about the command itself not being found, that is an install problem rather than an update problem. The guide to installing Claude Code covers PATH fixes and each platform's installer.

What is a sensible update routine?

Most people do not need a routine, because the native installer handles it. If you use Homebrew, WinGet or a Linux package manager, build the upgrade into something you already do. A weekly system update covers apt, dnf and apk. For a team, agree on one channel and one minimum version so that a shared project behaves the same on every laptop.

1. claude --version          # note the current version
2. Run the upgrade command for your install method (see the table above)
3. Open a new terminal, then: claude --version
4. /release-notes            # skim what changed, inside a session
5. If something broke, install the previous version number with the
   native installer and set DISABLE_AUTOUPDATER until you know why

If you are still deciding what to build with Claude Code, browse ideas on the board. Each one comes with a generated build prompt you can paste straight into a fresh session. The Claude Code tutorial walks through a first session after the update.