How to Update Claude on Linux | Differences Between claude update and npm

Three Update Tracks for Claude Code on Linux

The update process on Linux differs by installation method. The first step is knowing which method you used. The official documentation defines the following tracks:

Regardless of installation method, claude update for immediate updates and claude --version for version verification are universally available. Supported Linux environments include Ubuntu 20.04 or later, Debian 10 or later, and Alpine Linux 3.19 or later, with at least 4GB RAM and x64/ARM64 architecture required. For installation instructions themselves, see our separate article How to Use the Claude Linux App.

Official Installer Version: Auto-Updates and Checking with claude doctor

When installed via the official installer (curl -fsSL https://claude.ai/install.sh | bash), Claude Code periodically checks for updates at startup and during operation. Updates are downloaded and installed in the background, taking effect on the next launch. Users generally do not need to do anything manually.

To verify that updates were applied correctly, run the following command to display the result of the most recent update attempt:

claude doctor

claude doctor diagnoses not just version information, but also installation and configuration issues. Note that if you installed the npm global version and do not have write permission to npm's global directory, auto-updates will fail and a one-time warning will appear at startup. In that case, claude doctor will guide you through the fix.

The claude update Command for Immediate Updates

If you want to apply the latest version right away without waiting for the next launch, run the following command regardless of your installation method:

claude update
claude --version

claude update invokes the built-in updater, so you can update without needing to remember npm commands. After updating, verify the version with claude --version and cross-check it against the latest releases on the GitHub Releases page. Claude Code releases new features, model support, and bug fixes every few weeks.

The npm Update Pitfall — Don't Use npm update -g

For globally installed npm versions, the most common mistake is using npm update -g. The official documentation explicitly states:

To upgrade, run npm install -g @anthropic-ai/claude-code@latest. Using npm update -g respects the semver range from installation time and may not upgrade to the latest release.

The correct update command for the npm version is therefore this single command:

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

If an old binary persists and causes unstable behavior, a clean reinstall is effective. The steps are as follows:

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

Avoid using sudo npm install -g, as it introduces permission and security issues. If you encounter permission errors, the official recommendation is to reconfigure npm's prefix settings rather than using sudo.

Update Commands for apt / dnf / apk Package Versions

Anthropic publishes signed apt/dnf/apk repositories. These versions are not auto-updated by Claude Code itself — they are updated through the system's standard upgrade flow. The update commands for each are as follows:

# 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

The reason apt/dnf/apk remain manual is that these upgrades require administrator privileges. While Homebrew and WinGet support automatic upgrades when CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE is set to 1, Linux package managers are not included in this behavior. Also note that Claude Code may notify you of an update before the new version is available in the package manager — in that case, the upgrade will fail. Wait a moment and try again.

Choosing Update Speed vs. Stability — Release Channels and Version Pinning

The freshness of updates you receive can be controlled with the autoUpdatesChannel setting. There are two options:

• "latest" (default): Receive new features as soon as they are released
• "stable": Use a version approximately one week behind that skips releases with major regressions

Configure this in settings.json or change it via "Auto-update channel" in /config:

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

minimumVersion sets a lower bound for updates — neither auto-updates nor claude update will install versions older than this value. Switching from latest to stable will not downgrade an already-newer installation, making it a safe transition when moving to stable-channel operation. For organization-wide enforcement, this can be applied globally through managed settings.

Disabling Auto-Updates — DISABLE_AUTOUPDATER and DISABLE_UPDATES

To disable auto-updates, use one of two environment variables depending on your goal. To stop only background update checks, add the following to the env section of settings.json:

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

DISABLE_AUTOUPDATER only stops the automatic check — manual updates via claude update or claude install still work. To block all update paths including manual ones, use DISABLE_UPDATES instead. This is useful for in-house distributions where you want to lock users to a specific version.

Updating to a Specific Version and Rolling Back

If you need to avoid a problematic release or revert to an older version for testing, you can install a specific version. The official installer accepts a version number or channel as an argument:

# Specify a particular version (official installer)
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

For the npm version, pin to a specific version using @<version>:

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

Settings, allowed tools, MCP server configurations, and session history are stored in ~/.claude/ and are preserved across updates and rollbacks. You do not need to reconfigure after switching versions.

Troubleshooting When Updates Won't Apply

If updates aren't taking effect, work through the following steps in order:

1. Check version and diagnostics: Use claude --version and claude doctor to understand the current state and the result of the most recent update attempt
2. Review npm permissions: Auto-updates fail if the global directory is not writable. Do not use sudo npm install -g; follow the fix suggested by claude doctor
3. Check Node.js version: The npm version requires Node.js 18 or later. Verify with node --version
4. Suspect package propagation delay: When apt/dnf/apk reports an update available but the upgrade fails, the package may not yet be distributed. Wait and try again
5. Perform a clean reinstall: If none of the above help, uninstall the npm version and reinstall with @latest

If the issue persists, check GitHub Issues or the official setup and update documentation for known problems.

Summary

• Update behavior splits into three tracks depending on installation method (official installer = automatic / npm and apt-based = manual)
• The official installer version auto-updates in the background; verify results with claude doctor
• claude update applies updates immediately regardless of installation method; confirm with claude --version
• For npm versions, updating with @latest specified is required — npm update -g is not sufficient
• For apt/dnf/apk versions, update via the system's standard upgrade commands such as sudo apt upgrade claude-code
• Control update speed with autoUpdatesChannel, set a floor with minimumVersion, and disable auto-updates with DISABLE_AUTOUPDATER