Claude Code の画面下に赤字で Auto-update failed · Run claude doctor と出続ける、あるいは npm install -g @anthropic-ai/claude-code が npm error code ENOTEMPTY で止まるときの手順です。npm で入れている場合に起きるもので、更新の途中で残った一時フォルダを消して入れ直せば、その場は直ります。繰り返し起きるなら、npm 版をやめてネイティブ版に移すのが根本的な対処です。
確認環境は Claude Code 2.1.327、macOS 26.6.2、2026-11-19 です。
症状
セッション下部のフッタに、赤字で次のように出ます。
Auto-update failed · Run claude doctor
ヒントの付いた別の文言もあります(Claude Code 本体の文字列から確認したもので、公式ドキュメントの対応表には載っていません)。
Auto-update failed: no write permission to npm prefix
手動で更新しようとして npm install -g @anthropic-ai/claude-code を実行すると、次のように止まります。公式ドキュメントに載っている出力です。パスは環境によって変わります。
npm error code ENOTEMPTY
npm error syscall rename
npm error path /home/you/.nvm/versions/node/v22.13.1/lib/node_modules/@anthropic-ai/claude-code
npm error dest /home/you/.nvm/versions/node/v22.13.1/lib/node_modules/@anthropic-ai/.claude-code-tVWAnUUt
npm error errno -39
npm error ENOTEMPTY: directory not empty, rename '...'
結論
- フッタの赤字は、背景での自動更新が入らなかったという表示です。公式によると、何もしなくても作業は続けられます。
- 公式の最初の対処は、シェルで
claude updateを実行することです。そのときに出るエラーを見て、原因を切り分けます。 - npm 版で
ENOTEMPTYが出ているなら、npm error pathが指すフォルダと、隣にある.claude-code-*を消してから入れ直します。 - 何度も繰り返す人は、npm 版をやめてネイティブ版に移すと止まります。ただしこれは issue での報告と本体の案内文に基づく対処で、公式の対応表にはありません。
原因
Auto-update failed というフッタの文言自体は、更新が入らなかったことしか伝えません。公式によると、claude doctor の Last update attempt: failed (install_failed) という行も日付が分かるだけで、原因は出ません。原因は claude update を実行して、そこに出るエラーで確かめます。
npm 版で原因が ENOTEMPTY の場合は、次のような流れだと報告されています。
- npm はグローバルパッケージを更新するとき、古いフォルダを
.claude-code-XXXXという名前の一時フォルダへ移し、新しい版を置きます。 - 途中で中断されると、この一時フォルダが残ります。以降の更新では、同じ移動が「フォルダが空でない」ことで失敗し続けます(issue #12026)。
- 更新の対象が、いま動いている Claude Code 自身であることも原因として挙がっています(issue #8837 の報告者の推測です)。
issue #8837 は「6 回以上、手作業で直す必要があった」という報告で、同じ手順の繰り返しになることが分かります。後述のとおり、公式の案内も「残骸の削除」と「入れ直し」の 2 段です。
手元で確かめた結果
この Mac はネイティブ版で、npm 版の Claude Code は入っていません。そのため ENOTEMPTY そのものは再現していません(再現には npm 版を入れて更新を中断させる必要があり、手元の環境を壊すので行っていません)。確かめられたのは、自分の環境がどちらの版かを見分ける部分です。
$ which -a claude
~/.local/bin/claude
$ ls -la ~/.local/bin/claude
lrwxr-xr-x 1 ... ~/.local/bin/claude -> ~/.local/share/claude/versions/2.1.327
$ claude --version
2.1.327 (Claude Code)
~/.local/bin/claude が ~/.local/share/claude/versions/ への symlink なら、ネイティブ版です。公式のインストール確認の節も、ネイティブ版は ~/.local/share/claude/versions/ への symlink になると説明しています。
npm 版が入っているかは、次で分かります。
$ npm -g ls @anthropic-ai/claude-code
/usr/local/lib
`-- (empty)
(empty) なら npm 版は入っていません。入っていれば、バージョン付きで 1 行出ます。
claude update と claude install のヘルプは次のとおりです。更新はインストール方法ごとに別の経路になります。
$ claude update --help
Usage: claude update|upgrade [options]
Check for updates and install if available; package-manager installs update
through the package manager
$ claude install --help
Usage: claude install [options] [target]
Install the Claude Code native build. Use [target] to pick a version (stable,
latest, or a version number)
claude install は、ネイティブ版を入れるコマンドです。
直し方
1. まず claude update を実行する
フッタの赤字だけが出ているなら、公式の案内どおりシェルで次を実行します。
claude update
成功すれば Successfully updated from で始まる行が出ます。ここでエラーが出たら、そのエラーの文言で公式の Find your error の表を引きます。npm error code ENOTEMPTY なら次の手順です。
2. ENOTEMPTY のとき: 残骸を消して入れ直す
npm error path の行が、npm が動かせなかったフォルダです。まず公式の手順どおり、npm root -g が示す場所のものを消します(macOS / Linux)。
rm -rf "$(npm root -g)/@anthropic-ai/claude-code"
続けて、前の失敗で残った一時フォルダを消します。zsh で no matches found と出たら、残骸は無かったということです。
rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*
nvm で Node の版を切り替えたあとなどは、npm error path のフォルダが npm root -g の場所と違うことがあります。その場合は、エラーに出ているフォルダを直接消します。
入れ直します。
npm install -g @anthropic-ai/claude-code
claude --version
2.1.327 (Claude Code) のようにバージョンが出れば完了です。Windows の PowerShell では、削除を次のようにします(公式の手順です)。
Remove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"
3. 繰り返すなら、ネイティブ版に移す
issue #8837 のように何度も同じ失敗が起きるなら、npm 版のままにしておく理由はあまりありません。Claude Code 本体の警告文にも Run claude install to switch to the native installer (no sudo) という文言があります(本体の文字列から確認したもので、公式ドキュメントには載っていません)。
ネイティブ版は公式のインストールスクリプトで入れます。
curl -fsSL https://claude.ai/install.sh | bash
インストール後、~/.local/bin が PATH に入っていないと claude: command not found になります。その直し方は、別の記事にまとめています。
そのあと、npm 版を消して、claude が 1 つだけになっていることを確かめます。公式は、複数のインストールが混ざっているときは 1 つだけ残すように案内しています。
npm uninstall -g @anthropic-ai/claude-code
which -a claude
which -a claude に出る行が ~/.local/bin/claude の 1 行だけなら、移行は完了です。
直らないとき
-
claude updateが別のエラーを出す場合は、そのエラー文言で公式の対応表を引きます。たとえばRelease verification failed for Claude Codeは、同じコマンドをもう一度実行します。 -
Auto-update failed: no write permission to npm prefixのように、書き込み権限が理由の場合は、npm のグローバルフォルダが root 所有になっている可能性があります。sudoで入れ直さず、ネイティブ版への移行か nvm の利用が、本体の案内に沿った選び方です。 -
claude --versionで出る版が更新後も変わらないときは、複数のインストールが混ざっています。which -a claudeの結果を見て、残すものを 1 つに決めます。 - それでも解決しないときは、公式の Still stuck に従い、メッセージ全文を添えて報告します。
同じ原因で出る別のメッセージ
npm 版では、更新が本体を入れ替えている最中に、バックグラウンドセッションの起動が失敗することもあります。公式の Error reference には、次のような EACCES の例があります。
Couldn't start the background service — spawn background service: EACCES: permission denied, posix_spawn '/usr/local/lib/node_modules/@anthropic-ai/claude-code/bin/claude'
公式によると、これは npm install -g @anthropic-ai/claude-code が本体を入れ替えている最中に起きるのが通常です。npm 版では Claude Code が入れ替えの完了を待って自動で再試行します。更新が終わってから開き直せば解消します。詳しくは公式の EACCES when starting a background session を見てください。
Claude Code で出るほかの英文エラーと、それぞれの対処は、早見表にまとめています。
参考
- 公式 Troubleshoot installation and login(Auto-update failed): https://code.claude.com/docs/en/troubleshoot-install#auto-update-failed
- 公式 Troubleshoot installation and login(npm ENOTEMPTY error during update or reinstall): https://code.claude.com/docs/en/troubleshoot-install#npm-enotempty-during-update-or-reinstall
- issue #8837(Recurring auto-update failures with ENOTEMPTY error): https://github.com/anthropics/claude-code/issues/8837
- issue #12026(Auto-update fails repeatedly with ENOTEMPTY error on macOS with nvm): https://github.com/anthropics/claude-code/issues/12026