To learn **how to update Claude Code**, the required command depends directly on how you initially installed the CLI tool. For native standalone installations on macOS, Linux, or Windows, Claude Code updates automatically in the background on startup, or you can force an instant manual upgrade by executing `claude update` in your terminal. If you installed Claude Code as a global Node.js package, run `npm install -g @anthropic-ai/claude-code@latest` to pull the latest native binary. Package manager installations like Homebrew (`brew upgrade claude-code`) or WinGet (`winget upgrade Anthropic.ClaudeCode`) follow their own respective package workflows.
Keeping Claude Code updated ensures access to the latest agentic features, critical bug fixes, improved context window management, and immediate support for newly released Anthropic models. This step-by-step tutorial covers every update method across all operating systems, explains release channel configuration, and resolves common upgrade issues.
## Prerequisites and Identifying Your Installation Type
Before running update commands, verify your active version and identify which installation mechanism manages your binary. Attempting an npm update command on a standalone curl-installed binary will have no effect.
Open your terminal (Terminal on macOS/Linux, PowerShell or CMD on Windows) and run:
“`bash
claude –version
“`
A working installation outputs the active version number:
“`text
2.1.211 (Claude Code)
“`
Next, run the built-in diagnostic tool:
“`bash
claude doctor
“`
Inspect the `Launcher` and `Auto-updates` lines. If the launcher points to `~/.local/share/claude/versions/`, you are using the native standalone installer. If the path points to an npm global directory, your installation is managed via npm.
## Method 1: Updating Claude Code via Native Installer
The native installer is Anthropic’s recommended distribution format across macOS, Linux, and Windows. It bundles native binaries without requiring a local Node.js runtime.
### Automatic Background Updates
Native installations feature automated background updates. Claude Code checks for new releases on startup and periodically while active. When an update is detected, it downloads silently into `~/.local/share/claude/versions/` (or `%USERPROFILE%\.local\share\claude\versions` on Windows) and applies automatically the next time you start `claude`.
### Manual Update Command
If you want an immediate update without waiting for the background polling cycle, run:
“`bash
claude update
“`
When an update is available and downloads, the CLI displays:
“`text
Successfully updated from 2.1.200 to version 2.1.211
“`
If you are already on the latest release, the command confirms:
“`text
Claude Code is up to date (2.1.211)
“`
### Re-running the Standalone Installer Script
If `claude update` fails due to network issues or corrupted files, you can rerun the installer over your existing installation. This refreshes your binary without altering your personal configuration files in `~/.claude/` or your project settings.
**On macOS, Linux, and WSL:**
“`bash
curl -fsSL https://claude.ai/install.sh | bash
“`
To target the stable channel explicitly:
“`bash
curl -fsSL https://claude.ai/install.sh | bash -s stable
“`
## Method 2: Updating Claude Code via npm
If you installed Claude Code as a global npm package, the native auto-updater cannot modify global system directories without explicit privileges.
### Upgrading to the Latest Release
To update a global npm installation, run:
“`bash
npm install -g @anthropic-ai/claude-code@latest
“`
> **Note:** Avoid running `npm update -g @anthropic-ai/claude-code`. The standard `npm update` command respects semantic versioning ranges from the original install and often fails to move you to the newest release. Always use `npm install -g …@latest`.
### Avoiding Sudo with npm
Never run `sudo npm install -g @anthropic-ai/claude-code`. Running global npm commands under root permissions leads to file permission conflicts (`EACCES`), creates security risks, and prevents Claude Code from managing its own cache directories. If you encounter permission errors, configure a user-owned npm directory or switch to the native installer.
## Method 3: Updating Claude Code on Windows
On Windows, developers can run Claude Code natively in PowerShell or CMD, or inside the Windows Subsystem for Linux (WSL).
### Native PowerShell and CMD Updates
If you installed Claude Code using Anthropic’s official Windows installer script, background updates are active. You can also trigger an immediate update by running:
“`powershell
claude update
“`
To force an update or repair the installation via PowerShell:
“`powershell
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest
“`
For standard Command Prompt (CMD):
“`cmd
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
“`
### Updating via WinGet
If you installed Claude Code using the Windows Package Manager, auto-updates are disabled by default. Run:
“`powershell
winget upgrade Anthropic.ClaudeCode
“`
*Important:* Windows locks executable files while a process is running. Close all active Claude Code terminal sessions before executing `winget upgrade`.
### Updating in WSL (Ubuntu/Debian)
If you run Claude Code inside WSL, your installation lives within Linux. Open your WSL shell and run:
“`bash
claude update
“`
## Method 4: Updating via Homebrew and Linux Package Managers
If your environment uses system package managers, updates follow your system toolchain.
### macOS Homebrew
Homebrew maintains two casks:
– `claude-code`: tracks the stable channel (typically lagging by one week to avoid regressions).
– `claude-code@latest`: tracks immediate releases.
Run the upgrade command for your installed cask:
“`bash
brew upgrade claude-code
# Or for the latest channel:
brew upgrade claude-code@latest
“`
Run `brew cleanup` periodically to reclaim disk space from old versions.
### Linux Package Managers (apt, dnf, apk)
For developers using official signed repositories:
**Debian and Ubuntu (apt):**
“`bash
sudo apt update && sudo apt upgrade claude-code
“`
**Fedora and RHEL (dnf):**
“`bash
sudo dnf upgrade claude-code
“`
**Alpine Linux (apk):**
“`bash
apk update && apk upgrade claude-code
“`
### Enabling Auto-Updates for Package Managers
To allow Claude Code to run `brew upgrade` or `winget upgrade` automatically in the background, set this environment variable in your shell profile:
“`bash
export CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1
“`
## Managing Release Channels and Version Pinning
Production environments often require stability over rapid daily updates.
### Switching Release Channels
Claude Code provides two release channels:
1. `latest` (Default): Receives features, tool improvements, and model updates immediately upon shipping.
2. `stable`: Serves versions approximately one week old, skipping releases with major regressions.
Configure your channel via `/config` -> **Auto-update channel**, or add this to `~/.claude/settings.json`:
“`json
{
“autoUpdatesChannel”: “stable”
}
“`
### Pinning a Minimum Version
To ensure your team or CI pipelines never fall below a specific version floor, define `minimumVersion` in `settings.json`:
“`json
{
“autoUpdatesChannel”: “stable”,
“minimumVersion”: “2.1.200”
}
“`
### Disabling Auto-Updates
In air-gapped systems or shared network storage clusters, automated background writes can cause session bus errors. To disable background polling, set `DISABLE_AUTOUPDATER` in `settings.json`:
“`json
{
“env”: {
“DISABLE_AUTOUPDATER”: “1”
}
}
“`
Manual updates via `claude update` remain available. To block all update paths completely, set `DISABLE_UPDATES=1`.
## Verifying the Update and Health Checks
Once an update completes, verify the installation to confirm the binary is active and configuration files remain valid.
### 1. Check the Version
“`bash
claude –version
“`
### 2. Run Diagnostics
Run `claude doctor` to inspect the installation health:
“`bash
claude doctor
“`
The diagnostics check verifies binary architecture, settings schema validation, auto-update timestamps, launcher integrity, and API connectivity.
If you use custom workflows, such as proxying models with a Claude Code Router or benchmarking terminal tools from our OpenCode vs Claude Code comparison, running `claude doctor` ensures your environment variables and hooks remain intact. For multi-agent terminal environments, see our guide on Orca IDE.
## Troubleshooting Common Update Errors
| Error Symptom | Probable Cause | Resolution |
|---|---|---|
| WinGet Upgrade Failed (File Locked) | Claude Code is active and holding a lock on claude.exe. |
Close all active PowerShell, CMD, and IDE terminal windows running Claude Code, then rerun winget upgrade Anthropic.ClaudeCode. |
| npm EACCES / Permission Denied | npm global directory requires root permissions. | Do not use sudo. Configure a user-owned npm directory or switch to the native standalone installer. |
| Command Not Found after Update | The launcher symlink in ~/.local/bin is broken or missing from PATH. |
Remove ~/.local/bin/claude, ensure export PATH="$HOME/.local/bin:$PATH" is set, and rerun the install script. |
### Resolving Broken Custom Launchers
On macOS and Linux, the native installer places a symlink at `~/.local/bin/claude` pointing to `~/.local/share/claude/versions/`. If you modified this symlink manually, auto-updates will download new binaries into the versions folder but will leave your symlink untouched. To restore standard launcher management:
“`bash
rm -f ~/.local/bin/claude
curl -fsSL https://claude.ai/install.sh | bash
“`
## Frequently Asked Questions (FAQ)
### How do I check if Claude Code updated successfully?
Run `claude –version` in your terminal to see the current active version string, or execute `claude doctor` for a full status report showing update history, active channel, and binary integrity.
### Does updating Claude Code overwrite my CLAUDE.md or project settings?
No. Updating Claude Code only replaces the executable binary and launcher symlink. Your project instructions (`CLAUDE.md`), global preferences (`~/.claude/settings.json`), authentication credentials, and session histories are stored separately and remain untouched.
### Can I revert or downgrade to an earlier version of Claude Code?
Yes. With the native installer, you can install a specific version. On macOS/Linux, run `curl -fsSL https://claude.ai/install.sh | bash -s
## Summary
Updating Claude Code keeps your developer workflow equipped with the latest agentic tools, bug fixes, and model support. For native standalone installations, automated background updates handle routine upgrades seamlessly, while `claude update` provides instant on-demand control. For npm users, remember to execute `npm install -g @anthropic-ai/claude-code@latest` without sudo. Pin versions using `settings.json` when your environment requires strict reproducibility, and run `claude doctor` to verify system health after every update.
Hi, I’m Mark, the author of Clever IT Solutions: Mastering Technology for Success. I am passionate about empowering individuals to navigate the ever-changing world of information technology. With years of experience in the industry, I have honed my skills and knowledge to share with you. At Clever IT Solutions, we are dedicated to teaching you how to tackle any IT challenge, helping you stay ahead in today’s digital world. From troubleshooting common issues to mastering complex technologies, I am here to guide you every step of the way. Join me on this journey as we unlock the secrets to IT success.
