How to Fix Claude Code Failed to Auto-Update on macOS Sonoma (ENOTEMPTY npm Error)

I recently ran into an annoying issue while trying to upgrade the Claude Code CLI on macOS Sonoma. Instead of updating, npm threw this error:

npm error code ENOTEMPTY
npm error syscall rename
npm error path /Users/username/.npm-global/lib/node_modules/@anthropic-ai/claude-code
npm error dest /Users/username/.npm-global/lib/node_modules/@anthropic-ai/.claude-code-XXXXXX
npm error errno -66
npm error ENOTEMPTY: directory not empty, rename ...

If Claude Code says it failed to auto-update on macOS Sonoma, this is likely the exact error you're seeing.

Your global Node installation path matters

Before you start, it's important to know where your global npm modules are installed, because the fix depends on it:

• Custom npm prefix (.npm-global): Your global modules live in ~/.npm-global/lib/node_modules/
• nvm (Node Version Manager): Your global modules live in ~/.nvm/versions/node/<version>/lib/node_modules/
• Homebrew Node: Your global modules live in /usr/local/lib/node_modules/

If you're unsure which you have, run:

npm config get prefix

This will show you the exact path where global installs go. The fix steps below cover all three cases.

Why this happens

The problem isn't Claude itself but npm on macOS. During a global install or upgrade, npm tries to rename the existing claude-code folder to a temporary one (like .claude-code-XXXXXX). If any leftover files (or even hidden macOS files like .DS_Store) remain, npm can't finish the rename, and the install fails.

This issue is especially common on macOS Sonoma and later with npm 10+ and Node 22+, due to stricter file locking in APFS (the default macOS filesystem).

Step-by-step fix

For all users (before step 1)

First, check if you have leftover temporary directories from a failed install:

ls -la $(npm config get prefix)/lib/node_modules/@anthropic-ai/ | grep "\.claude-code-"

If you see folders like .claude-code-xxxxx, note that these need to be removed too — they're what cause the ENOTEMPTY error.

Step 1: Remove the existing Claude Code folder

Replace $(npm config get prefix) with your actual prefix (it will auto-expand):

rm -rf $(npm config get prefix)/lib/node_modules/@anthropic-ai/claude-code

For nvm users specifically, this expands to:

rm -rf ~/.nvm/versions/node/$(node -v)/lib/node_modules/@anthropic-ai/claude-code

Step 2: Remove leftover temporary directories

This is the critical step that many guides miss. npm sometimes leaves hidden temp directories when a rename fails. Delete them:

rm -rf $(npm config get prefix)/lib/node_modules/@anthropic-ai/.claude-code-*

For nvm users specifically:

rm -rf ~/.nvm/versions/node/$(node -v)/lib/node_modules/@anthropic-ai/.claude-code-*

Why this matters: These hidden .claude-code-* folders are what caused the original ENOTEMPTY error. Deleting them is safe and necessary to prevent the same error on reinstall.

Step 3: Clear the npm cache

npm cache clean --force

Step 4: Reinstall Claude Code globally

npm i -g @anthropic-ai/claude-code

That's it — the install should now complete cleanly.

If reinstall still fails (fallback option)

If you still hit an ENOTEMPTY error after these steps, try installing with the --no-bin-links flag, which bypasses npm's rename step:

npm install -g @anthropic-ai/claude-code --no-bin-links

This flag prevents npm from trying to rename link targets, which is the usual trigger for this macOS issue.

Alternative: Skip the global install (recommended for nvm and macOS users)

If you'd rather not deal with global installs (and their conflicts), you can just run Claude Code with npx:

npx @anthropic-ai/claude-code

Why this is the safest option:

• Always fetches the latest version automatically
• Avoids global node_modules conflicts entirely
• Works seamlessly on nvm, Homebrew Node, and custom npm prefixes
• No auto-update issues because there's nothing to update — it's always fresh

This is especially useful if you're on nvm or macOS Sonoma, since global npm installs sometimes fail due to file rename locks.

Troubleshooting: Still hitting errors?

If the above steps don't work, check the npm debug log to confirm the error:

cat ~/.npm/_logs/*-debug-0.log | grep -A 5 "ENOTEMPTY"

If you see ENOTEMPTY and rename in the output, it confirms that the steps above should fix it. If the error is different, the issue is likely something else (like a network timeout or permissions problem).

Common next steps:

• Double-check that you ran both rm -rf commands (the main folder AND the .claude-code-* temp folders)
• Make sure you ran npm cache clean --force between removal and reinstall
• Try the --no-bin-links fallback option mentioned above
• As a last resort, use npx instead of a global install

Conclusion

If you see the Claude Code failed to auto-update error on macOS Sonoma with ENOTEMPTY, the fix is straightforward: delete the old install (including hidden temp folders), clear the cache, and reinstall. The issue comes from npm's handling of leftover directories on macOS due to APFS file locking, not from Claude itself.

For a hassle-free experience, especially on nvm or Sonoma, just use npx @anthropic-ai/claude-code instead — it sidesteps the whole problem.

Let me know in the comments if you've hit other upgrade quirks, and subscribe for more practical dev fixes.

Thanks, Matija