How to control Claude Code auto-updates across a team

Native and npm installs of Claude Code update themselves in the background. Homebrew and WinGet installs do not, unless you opt in, and apt, dnf and apk installs do not update through Claude Code at all. To control updates across a team, set DISABLE_AUTOUPDATER to stop background checks, or DISABLE_UPDATES to block manual updates too.
Which install methods auto-update
The setup page documents update behaviour for each install method, and the methods differ. Native installs check for updates on startup and periodically while running, then install in the background. The new version takes effect the next time Claude Code starts. Npm installs update too, and the page covers them with the same disable setting. Homebrew and WinGet do not update by default, and the Linux package managers do not update through Claude Code. Record the method on every machine first, because the controls in this post act on installs that update themselves.
| Install method | Updates in the background | Manual update command | Notes |
|---|---|---|---|
| Native installer (curl or PowerShell) | Yes | claude update |
Release channel set by autoUpdatesChannel |
npm (@anthropic-ai/claude-code) |
Yes | npm install -g @anthropic-ai/claude-code@latest |
Avoid npm update -g. Do not use sudo |
Homebrew (claude-code or claude-code@latest) |
No, unless CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE is 1 |
brew upgrade claude-code or brew upgrade claude-code@latest |
The cask you install picks the channel |
WinGet (Anthropic.ClaudeCode) |
No, unless CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE is 1 |
winget upgrade Anthropic.ClaudeCode |
The upgrade can fail while Claude Code runs |
| apt, dnf, apk | No, through Claude Code | sudo apt update && sudo apt upgrade claude-code, sudo dnf upgrade claude-code, apk update && apk upgrade claude-code |
The repository you add picks the channel |
Record each machine’s install method and version
Start with a read-only inventory. The commands below print the version and the installation diagnostics, and neither one starts a session. The setup page says claude doctor reports install health, settings-file errors, and warnings with suggested fixes.
- Run
claude --versionand record the version number at the start of the output. - Run
claude doctorand note any installation warning. On native and npm installs, find the Auto-updates line. - If the output reports a failed update attempt on a native install, follow the Auto-update failed entry in the session footer, as the page directs.
- Sort each machine into a row of the table above. Machines in the Homebrew, WinGet and Linux package manager rows need their own upgrade process.
claude --version
claude doctor
Set the release channel and a version floor
The autoUpdatesChannel setting picks the release channel. latest is the default and receives new features as soon as they ship. stable serves a version that is typically about one week old and skips releases with major regressions. Set it in /config under Auto-update channel, or in a settings file.
{
"autoUpdatesChannel": "stable"
}
The page warns that a native installation on stable updates to the stable version even when that version is older than the one you run. To avoid the downgrade, set minimumVersion to your current version. Background updates and claude update then refuse to install anything below it. The docs use 2.1.323 as their example. Replace it with the output of claude --version on each machine, and set autoUpdatesChannel in the same edit.
{
"autoUpdatesChannel": "stable",
"minimumVersion": "2.1.323"
}
Turn off background updates
DISABLE_AUTOUPDATER stops the background check. The page sets it in the env key of a settings file. Manual updates still work after you set it, because claude update is not blocked.
{
"env": {
"DISABLE_AUTOUPDATER": "1"
}
}
Confirm the change with claude doctor. On a native or npm installation, the Auto-updates line should read disabled (set by env: DISABLE_AUTOUPDATER) instead of enabled. The environment variables reference describes the setting as “Set to 1 to disable automatic background updates. Manual claude update still works.”
Block manual updates with DISABLE_UPDATES
DISABLE_UPDATES is the stricter setting. The reference says it blocks all updates, including claude update and claude install. The setup page recommends it when you distribute Claude Code through your own channels and need users to stay on the version you provide.
{
"env": {
"DISABLE_UPDATES": "1"
}
}
Shared home directories need this stricter setting. The setup page says that on network storage, DISABLE_AUTOUPDATER alone is not enough, because users can still run claude update and claude install. An npm auto-update on one machine can run an in-place upgrade that removes the binary other machines are still running. Set DISABLE_UPDATES, and install new versions with your own tooling.
Compare the controls
The four controls do different jobs, and they can be combined. Use this table to pick the one that answers the question you have.
| Control | Set with | Stops background updates | Stops claude update |
What it does not do |
|---|---|---|---|---|
DISABLE_AUTOUPDATER |
env value "1" |
Yes | No | Leaves manual updates working |
DISABLE_UPDATES |
env value "1" |
Yes | Yes, and claude install too |
Stops all updates, including manual ones |
autoUpdatesChannel |
"stable" or "latest" |
No, it picks the channel | No | Can move a native install to an older stable build |
minimumVersion |
A version number | No | Refuses versions below the floor | Sets a floor only, not a ceiling or a pin |
The docs do not say whether DISABLE_UPDATES or DISABLE_AUTOUPDATER affects an upgrade you run by hand with Homebrew or WinGet. Test that on one machine before you rely on it.
Set the policy for the whole team
Settings resolve by level. From highest to lowest, the order is managed settings, the command line, project local, shared project, and user. An env block in a settings file follows the same order, so a value at a higher level overrides the same key below it.
For an organization, managed settings are the right place to enforce these controls. The setup page says you can enforce a consistent release channel across your organization with managed settings. In managed settings, minimumVersion sets an organization-wide floor that user and project settings cannot override.
Do not rely on a committed .claude/settings.json for a control that must hold everywhere. The settings page says some values in a shared .claude/settings.json, env values included, wait until each teammate trusts the folder, and a few keys never apply from a repository file. File-based managed settings reload when the file changes. Managed settings delivered from the admin console reach a running session on a schedule, so restart a pilot session before you judge a change. Check the Setting sources line in /status to confirm which files loaded.
Pin an exact version: what the docs do not cover
The docs define minimumVersion as a floor. It stops background updates and claude update from installing anything below that version, but it does not stop newer releases from installing, so it is not a pin. The setup page says that to make Claude Code refuse to start outside a version range, you use the managed requiredMinimumVersion and requiredMaximumVersion keys instead.
The installer accepts a version number. The setup page says the channel you choose at install time becomes your default for auto-updates. The page does not say that a version number chosen at install time is held in place. If you need one exact version kept on every machine, the documented route is DISABLE_UPDATES with your own distribution. The docs describe no other way to pin, so confirm the behaviour on a test machine before you roll it out.
Roll out the controls in order
This is a rollout order built from the steps above. It is not a product workflow, and you can run it with any tooling.
- Inventory the install method and version on every machine.
- Choose a release channel. Set
minimumVersionon the machines that must not move. - Set
DISABLE_AUTOUPDATERon native and npm machines. UseDISABLE_UPDATESwhere your own tooling delivers every version. - Move the controls that must apply to every user into managed settings, and restart a pilot session.
- Confirm the result with
claude doctorand/statuson a pilot machine, then widen the group. - Re-read the setup and environment variable pages at each release. The key names and defaults come from pages that change.
Enforcing this across the team
These controls are Claude Code’s own settings, and they work without any Nirmata product. This post makes no claim about what any product does with them. The governance for AI coding agents page covers the category, and the AIControls page describes that product separately. For the managed settings file itself, read the Claude Code managed settings post. For plugin updates, read the plugins and marketplaces post. For MCP server versions, read the MCP pinning post.
Frequently asked questions
Will a new Claude Code model fail to run if our team is on the stable channel?
It can. The setup page says a newly launched model can require a Claude Code version newer than the one the stable channel serves. To run that model, the page says to move to the latest channel. You can switch with autoUpdatesChannel set to latest, or with /config. Decide in advance which machines may move, and record the switch, because a stable-channel fleet will not pick up the model until its channel changes.
Can a shared settings file in a repository turn off auto-updates for everyone?
Not reliably. The settings page says some values in a shared .claude/settings.json, env values included, wait until each teammate trusts the folder, and a few keys never apply from a repository file. Deny and ask rules apply right away. For a control that must hold on every machine, put it in managed settings, which take precedence over user, shared project and local files.
Does DISABLE_AUTOUPDATER change how Homebrew or WinGet installs update?
Not by itself. Homebrew and WinGet installs do not update by default. The env-vars reference says CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE set to 1 lets Claude Code run the upgrade for those two. apt, dnf and apk installs do not update through Claude Code at all, and their upgrades need elevated privileges, so run them through your normal system process.
How do we find out why an auto-update failed?
Run claude doctor. It shows the result of the last update attempt that Claude Code recorded. On a native install that reports a failed attempt, the setup page points to the Auto-update failed entry in the session footer for next steps. Run claude doctor again after each change, and check that the Auto-updates line shows the state you expect.