Docs: clarify or restore documented way to disable auto-updates

[sakal-s]

The settings reference at https://code.claude.com/docs/en/settings does not document any top-level key to disable auto-updates. The only update-related keys listed are autoUpdatesChannel ("stable" / "latest") and minimumVersion.

Community sources and an older docs page reference both:

• DISABLE_AUTOUPDATER=1 environment variable
• "autoUpdates": false settings key

Issues #10079 and #12564 both flag this inconsistency and were closed without a documented resolution.

Request

Could the docs either:

1. Document the supported way to fully disable auto-updates (env var, setting, or both), or
2. Explicitly state that auto-updates cannot be disabled and the closest supported behavior is autoUpdatesChannel: "stable" + minimumVersion.

Why this matters

Users who want a stable, predictable CLI experience (e.g., for team workflows, training material, or to avoid behavior changes mid-task) currently have no authoritative answer for how to pin or disable updates.

Environment

• Claude Code version: 2.1.131
• Platform: macOS (Darwin 25.3.0)

Related

• [DOCS] DISABLE_AUTOUPDATER env documentation refers to undocumented or non-existent setting #10079
• Documentation inconsistency: auto-update disable setting #12564

[sakal-s]

Additional finding: autoUpdatesProtectedForNative overrides autoUpdates: false

While debugging this on a real install, I found that ~/.claude.json contains an undocumented flag that appears to override the disable:

{
  "installMethod": "native",
  "autoUpdates": false,
  // ...
  "autoUpdatesProtectedForNative": true
}

With installMethod: "native" and autoUpdatesProtectedForNative: true, updates continue silently even though "autoUpdates": false is set. The native-install path appears to be treated as "protected" and ignores the user's disable preference.

Concrete repro

• Claude Code version: 2.1.131
• Platform: macOS (Darwin 25.3.0)
• Install method: native (/Users/<user>/.local/bin/claude)
• ~/.claude.json has "autoUpdates": false (line 4) and "autoUpdatesProtectedForNative": true (line 646)
• Behavior: silent updates still occur

Suggested doc additions

In addition to clarifying autoUpdates / DISABLE_AUTOUPDATER, the docs should:

1. Document the autoUpdatesProtectedForNative flag and the policy that native installs ignore autoUpdates: false.
2. Either provide a supported way for native-install users to opt out of updates, or document that native installs cannot opt out (and recommend a non-native install method for users who need a stable version).

[github-actions]

Found 3 possible duplicate issues:

1. [DOCS] Update docs missing DISABLE_UPDATES env var behavior #52192
2. [DOCS] DISABLE_AUTOUPDATER env documentation refers to undocumented or non-existent setting #10079
3. Documentation inconsistency: auto-update disable setting #12564

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[aria-inboxia]

Confirmed repro on macOS native install — additional data

Confirming sakal-s's finding that autoUpdatesProtectedForNative: true overrides autoUpdates: false on native installs. Adding fresh data for triage:

Environment:

• macOS (Darwin 25.4.0)
• installMethod: "native"
• ~/.claude.json:

  {
    "autoUpdates": false,
    "autoUpdatesProtectedForNative": true,
    "installMethod": "native"
  }

Observed behavior over 30-day window (analyzed via parsing ~/.claude/projects/**/*.jsonl version field):

• 23 distinct CC versions ran sessions in 30d (2.1.70 → 2.1.132)
• 4 versions installed in last 7 days alone (2.1.126 → 2.1.129 → 2.1.131 → 2.1.132)
• Despite autoUpdates: false, ~/.local/share/claude/versions/ keeps getting new entries

Working fix discovered via #52192:

Setting DISABLE_UPDATES=1 in the env block of ~/.claude/settings.json (added in v2.1.118 per changelog) actually stops the auto-updater. The older DISABLE_AUTOUPDATER=1 is also documented but #52192 notes it's strictly weaker.

Suggested doc fix:

The settings reference at https://code.claude.com/docs/en/settings should clarify that on native installs, the autoUpdates: false JSON flag is ignored when autoUpdatesProtectedForNative: true (which appears to be set automatically), and that DISABLE_UPDATES=1 env var is the actual working control.

Defense-in-depth I'm using locally (in case the env var is regressed in a future version):

1. DISABLE_UPDATES=1 + DISABLE_AUTOUPDATER=1 in settings.json env
2. Hardcopy of claude binary with macOS uchg (user-immutable) flag, ~/.local/bin/claude symlinked to it (outside versions/ dir so the updater can't reach it)

Happy to share the analyzer script that produced the 23-version count if useful for triage.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[chewybone]

im seeing tons of these tickets that get closed for inactivity, why is that? doesn't seem to be triaged at the very least

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.