Downgrade Claude Code, and make the downgrade stick

Why the downgrade did not stick

Native installations check for updates at startup and periodically while running, download in the background, and apply the new version the next time you start Claude Code. That is excellent default behaviour and exactly wrong when you are deliberately sitting on an older build. Install 2.1.89 without touching anything else and the updater treats it as a machine that has fallen behind.

So the order matters, and it is always the same three steps.

1. Stop the updater. Otherwise everything after this is temporary.
2. Install the version you want.
3. Verify. claude --version should print the exact version you asked for.

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

Native install

The native installer accepts a version number or a channel name, both at first install and afterwards through claude install.

claude install 2.1.89

claude --version    # prints e.g. 2.1.89 (Claude Code)
claude doctor       # reports install health and the last update attempt

If claude is not currently runnable at all, because the broken release is broken enough to not launch, go through the install script instead, which takes the same argument.

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

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

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 2.1.89 && del install.cmd

npm, Homebrew, and WinGet

npm

npm downgrades are the straightforward case, because the registry keeps every published version. At the time of writing there were 476 of them.

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

# what the dist-tags currently point at
npm view @anthropic-ai/claude-code dist-tags

# install an exact version
npm install -g @anthropic-ai/claude-code@2.1.89
claude --version

Homebrew

Homebrew casks do not offer a clean historical version pin. What they do offer is a channel choice by cask name: claude-code tracks stable and claude-code@latest tracks latest. If you are on the latest cask and hit a regression, moving to the stable cask is the supported move and is usually what you actually wanted.

brew uninstall --cask claude-code@latest
brew install --cask claude-code
claude --version

For an exact older build, uninstall the cask and use the native installer with a version argument instead. Mixing a pinned native install with an unpinned Homebrew cask on the same machine gives you two binaries and an unpredictable winner on PATH.

WinGet

winget install Anthropic.ClaudeCode --version 2.1.89

WinGet only serves versions that are still in its manifest history, so an old enough build may simply not be offered. The native installer has no such limit.

What you probably want instead: the stable channel

Most downgrades are not really "I need 2.1.89", they are "I keep getting bitten by new releases". There is a supported setting for exactly that. The stable channel serves a version that is typically about a week old and skips releases with major regressions. You stay current, just behind the wave.

{
  "autoUpdatesChannel": "stable"
}

The channel is honoured by background auto-updates and by claude update. Homebrew is the exception: there the channel is chosen by which cask you installed, not by this setting.

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

Pinning a version range for a team

Individual settings are advisory. If the point is that nobody on the team runs a build you have not qualified, the enforcing mechanism is managed settings, which user and project settings cannot override.

The pair to reach for when qualifying a release is requiredMinimumVersion and requiredMaximumVersion, because they constrain what actually runs rather than only what updates. A minimumVersion floor on its own will happily let the whole fleet move forward past the build you tested.

Finding the version you want, and getting back

You need a version number before any of this is useful, and Claude Code does not print a changelog at you.

• npm view @anthropic-ai/claude-code versions --json lists every published version, including builds you never installed.
• npm view @anthropic-ai/claude-code dist-tags shows what latest and stable currently resolve to.
• claude doctor reports the result of the most recent update attempt, which tells you what you were on before it moved.
• On macOS and Linux, ls ~/.local/share/claude/versions/ lists the builds still on disk, and a custom launcher keeps all of them.

# 1. remove the pin from ~/.claude/settings.json (DISABLE_AUTOUPDATER, minimumVersion)
# 2. then
claude update
claude --version

Questions people ask

Keep reading