How to update Claude Code, roll back a version or remove it completely

Claude Code ships often, and sooner or later three questions come up: how to update it, how to go back to an older version if the new one broke something, and how to remove it completely without leaving debris. The answer depends on how the program was installed. Below are the commands for each method and a separate section on keeping your gateway connection settings. Everything is based on the Claude Code installation documentation as of October 2026; versions, paths and commands change, so when in doubt check the current install page.

First, find out the version and install method

Checking the version:

claude --version

A working installation prints a version number like 2.1.211 (Claude Code). If your shell says the command is not found, the install directory is not on your PATH: open a new terminal window and check again.

For detailed diagnostics there is a command that changes nothing and does not start a session:

claude doctor

It shows the installation state, errors in settings files and the result of the last update attempt. The install method determines all the commands that follow:

If you have several installs (say native and npm), the one that runs may not be the one you updated. claude doctor reports such conflicts, and the documentation has a section on finding conflicting installations.

Claude CLI update: how to update Claude Code

A native installation updates itself. According to the docs, Claude Code checks for updates at startup and periodically while running, downloads them in the background, and the new version takes effect at the next launch. To avoid waiting, run:

claude update

After a successful update the command reports which version you moved from and to, and if you are on the latest it says there is nothing to update.

For the other methods the commands are:

Homebrew (the command depends on which package you installed), WinGet and npm:

brew upgrade claude-code
brew upgrade claude-code@latest
winget upgrade Anthropic.ClaudeCode
npm install -g @anthropic-ai/claude-code@latest

For npm the docs warn explicitly: do not use npm update -g, because it follows the original version range and may not bring you to the newest release, and do not run npm install -g with sudo. For apt, dnf and apk the upgrade commands are in the Linux packages section. Two details: Homebrew and WinGet can be made to update automatically with the CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 variable, and with a WinGet upgrade Windows may lock the executable while Claude Code is running. Close it and retry. Sometimes the package manager gets the new version with a delay after the notification: wait and try again later.

Update channel: latest or stable

The autoUpdatesChannel setting controls how fast you get new things. The value "latest" (the default) delivers new features immediately, while "stable" serves a version about a week old and skips releases with major regressions. You can set it through /config or in the settings file:

{
  "autoUpdatesChannel": "stable"
}

This helps if you want predictability. With one caveat from the docs: a newly launched model may require a Claude Code version newer than the stable channel serves. If after a new model appears the client does not accept it or reports a model selection error, switch to latest and update. The model identifiers the gateway accepts are listed at GET https://api.zukko.pro/v1/models.

How to roll back a version

If a new version broke your workflow, install the one you need explicitly. The native installer accepts a version number:

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

The documentation example uses version 2.1.89; substitute the one you want to return to. For Windows PowerShell and CMD there are equivalent commands on the same page. With npm the same is done like this:

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

So that background updating does not bring you back, turn it off. In ~/.claude/settings.json add:

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

This setting stops only the background check: claude update and claude install keep working. If you need to close all update paths, including manual ones, the docs have the DISABLE_UPDATES variable. After the rollback run claude --version to make sure you are on the intended version. Remember to lift the block later, or you will miss fixes.

How to remove Claude Code completely

Removal is done in two steps: the program, then the settings.

Step 1. Remove the program

Native install on macOS, Linux and WSL:

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

Windows PowerShell:

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

Other methods:

brew uninstall --cask claude-code          # or claude-code@latest
winget uninstall Anthropic.ClaudeCode
npm uninstall -g @anthropic-ai/claude-code

For apt, dnf and apk, besides removing the package, the documentation asks you to remove the repository entry, and the commands are spelled out there separately. After removal check that claude no longer runs. If it does, you still have a second install or a shell alias.

Step 2. Remove settings and history (optional)

A warning from the documentation: deleting configuration files erases all your settings, allowed tools, MCP server configurations and session history. If you do not need to, leave them: the program goes away and the settings will be useful on reinstall.

If you decided to erase everything, on macOS, Linux and WSL:

rm -rf ~/.claude
rm ~/.claude.json

Project settings are removed from the project directory:

rm -rf .claude
rm -f .mcp.json

Check the path before pressing Enter: rm -rf deletes without a way back. There is also a nuance: the VS Code and JetBrains extensions and the desktop app write to ~/.claude/ too. While any of them is installed the directory will reappear. For a complete removal, remove them first.

Keeping your gateway connection

Connecting Claude Code to Zukko consists of three variables: ANTHROPIC_BASE_URL=https://api.zukko.pro (without /v1), ANTHROPIC_AUTH_TOKEN with your fetch_... key, and ANTHROPIC_MODEL. Where they live decides the fate of your settings:

• In a shell profile (~/.zshrc, ~/.bashrc): uninstalling the program does not touch them, and a reinstall picks them up right away.
• In the env block of ~/.claude/settings.json: step 2 deletes the file together with the key.

Before cleaning, save the connection parameters. The full key is shown once at creation, so keep it in a password manager and not only in a Claude Code file. If the key is lost, create a new one in the dashboard↗ and revoke the old one. After reinstalling you can restore the connection with this block:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.zukko.pro",
    "ANTHROPIC_AUTH_TOKEN": "fetch_your_key",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5"
  }
}

Do not put such a file in a repository or copy it into cloud notes. A check after installing: run claude, send a short question and make sure a charge appears in the "Usage" section of the dashboard. If Claude Code asks you to sign in to an Anthropic account again, work through the article Claude Code asks for an Anthropic login↗. The full setup from scratch is in the Claude Code guide↗ and in the article Claude Code setup from scratch↗; for Windows there is a separate article↗.

FAQ

How do I know the update worked?

Run claude --version. The claude update command also reports which version you moved from and to, and claude doctor shows the result of the last auto-update attempt.

Will an update reset my settings?

Updating the program does not touch settings: they live in ~/.claude/, ~/.claude.json and your shell profile. They are erased only if you delete those files yourself.

What if claude still runs after I removed it?

It means another copy is installed or there is an alias in the shell. Run claude doctor and look for conflicting installs following the instructions in the documentation.

Do I need to update when a new model is released?

Not always. But if the client does not accept the new model and you are on the stable channel or have auto-update disabled, update to the latest version.