Updating Claude Code, and pinning it when you should not

Update it now

One command covers every install method, including the ones that do not auto-update.

claude update
claude --version

On success it prints Successfully updated from <old version> to version <new version>. If you are already current it prints Claude Code is up to date (<version>). Installs owned by Homebrew, WinGet or apk report Claude is up to date! instead, because the package manager is the one that moves the files. claude --version answers in the form 2.1.211 (Claude Code).

How auto-update actually works

A native install checks for updates at startup and periodically while running. New versions download and install in the background, then take effect the next time you start Claude Code. Nothing swaps underneath a running session, which is why a long agent run is never interrupted by an update and why the version you are running can be one behind the version on disk.

• On macOS and Linux the launcher is ~/.local/bin/claude, a symlink into ~/.local/share/claude/versions/. Versions land in that directory; the symlink decides which one runs.
• If you replace that launcher with your own script or symlink, the updater leaves it alone (from v2.1.207 onward) and keeps every installed version on disk, because it cannot tell which one your launcher needs.
• claude doctor reports the result of the most recent update attempt, plus a launcher the installer did not create.
• An npm global install that cannot write to the npm global directory shows a one-time notice at startup, and claude doctor lists the fixes.

Latest or stable: pick a channel

Auto-updates and claude update both follow a release channel. There are two, and the choice is a one-line setting.

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

You can also set the channel interactively with /config, under Auto-update channel. minimumVersion is a floor: background updates and claude update refuse to install anything below it, so switching from latest to stable cannot silently downgrade a machine that is already ahead. Switching channels in /config asks whether to stay put or allow the downgrade, and staying put writes that version into minimumVersion for you.

• Homebrew picks the channel by cask name, not by this setting: claude-code tracks stable, claude-code@latest tracks latest.
• The Linux repositories carry both channels in their URL path, so switching means editing the repository definition rather than a setting.
• Enterprise fleets can enforce a channel through managed settings, and can make Claude Code refuse to start outside a version range with requiredMinimumVersion and requiredMaximumVersion. Those are a harder guarantee than minimumVersion, which only constrains updates.

Turning updates off

Two variables, and they are not interchangeable. Reaching for the wrong one is why people report that they disabled auto-update and it updated anyway.

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

Pinning a version for CI and images

In a pipeline, a self-updating agent means the tool that produced the last green build is not the tool running today. When something regresses you cannot bisect it, because one of the variables changed itself.

# native installer, exact version
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89

# or, on a machine that already has Claude Code
claude install 2.1.89

# npm, if your CI already caches an npm store
npm install -g @anthropic-ai/claude-code@2.1.89

export DISABLE_AUTOUPDATER=1
claude --version   # assert this in the job if you want to be strict

FROM node:22-bookworm-slim
ARG CLAUDE_VERSION=2.1.89
RUN npm install -g @anthropic-ai/claude-code@${CLAUDE_VERSION}
ENV DISABLE_AUTOUPDATER=1

Rolling back a bad release

# what exists
npm view @anthropic-ai/claude-code versions --json | tail -20

# go back, native install
claude install 2.1.88
export DISABLE_AUTOUPDATER=1

claude --version

On Homebrew, the equivalent move is to switch casks rather than to name a version: claude-code is the stable channel and is the closest thing to a rollback the cask offers. Homebrew keeps old versions on disk after upgrades, so run brew cleanup occasionally to reclaim the space.

Before you blame a release

Most "the update broke it" reports are one of five things, and four of them are answered in under a minute.

Questions people ask

Keep reading