---
title: "Fix Claude Code Auto Update Failed on Mac (ENOTEMPTY npm Error)"
slug: "fix-claude-code-auto-update-macos-enotempty"
published: "2025-09-30"
updated: "2026-03-27"
validated: "2026-03-27"
categories:
  - "AI"
tags:
  - "Claude Code"
  - "auto-update failed"
  - "auto update failed"
  - "ENOTEMPTY"
  - "npm error"
  - "macOS Sonoma"
  - "Claude Code npm"
  - "update Claude Code"
  - "directory not empty"
  - "npm cache"
  - "global install"
  - "Anthropic"
  - "Node.js"
  - "troubleshooting"
llm-intent: "reference"
audience-level: "beginner"
framework-versions:
  - "node@20 (or node@18+)"
  - "npm@10 (or latest npm)"
  - "@anthropic-ai/claude-code@latest"
  - "macos@Sonoma (macOS 14+)"
  - "shell:bash"
status: "stable"
llm-purpose: "Fix Claude Code auto-update failures on macOS Sonoma caused by npm ENOTEMPTY rename errors. Step-by-step: delete old global install, clear npm"
llm-prereqs:
  - "Access to npm"
  - "Access to Node.js"
  - "Access to macOS Terminal"
llm-outputs:
  - "Completed outcome: Fix Claude Code auto-update failures on macOS Sonoma caused by npm ENOTEMPTY rename errors. Step-by-step: delete old global install, clear npm"
---

**Summary Triples**
- (How to Fix Claude Code Failed to Auto-Update on macOS Sonoma (ENOTEMPTY npm Error), focuses-on, Fix Claude Code auto-update failures on macOS Sonoma caused by npm ENOTEMPTY rename errors. Step-by-step: delete old global install, clear npm)
- (How to Fix Claude Code Failed to Auto-Update on macOS Sonoma (ENOTEMPTY npm Error), category, general)

### {GOAL}
Fix Claude Code auto-update failures on macOS Sonoma caused by npm ENOTEMPTY rename errors. Step-by-step: delete old global install, clear npm

### {PREREQS}
- Access to npm
- Access to Node.js
- Access to macOS Terminal

### {STEPS}
1. Follow the detailed walkthrough in the article content below.

<!-- llm:goal="Fix Claude Code auto-update failures on macOS Sonoma caused by npm ENOTEMPTY rename errors. Step-by-step: delete old global install, clear npm" -->
<!-- llm:prereq="Access to npm" -->
<!-- llm:prereq="Access to Node.js" -->
<!-- llm:prereq="Access to macOS Terminal" -->
<!-- llm:output="Completed outcome: Fix Claude Code auto-update failures on macOS Sonoma caused by npm ENOTEMPTY rename errors. Step-by-step: delete old global install, clear npm" -->

# Fix Claude Code Auto Update Failed on Mac (ENOTEMPTY npm Error)
> Fix Claude Code auto-update failed on macOS Sonoma with ENOTEMPTY npm error. Remove old install, clear cache, and reinstall in 4 steps or use npx.
Matija Žiberna · 2025-09-30

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.

---

## Diagnose your npm setup

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

- **Custom npm prefix** (e.g., `~/.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/`

To check which you have:

```bash
npm config get prefix
```

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

**Important:** If `npm config get prefix` doesn't match where Claude actually lives (check with `ls -l $(which claude)`), you may have a **prefix mismatch**—see the Troubleshooting section for how to fix this.

---

## Why this happens

The problem isn't Claude Code 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 in the directory, 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 APFS file locking and extended file attributes. The `--no-bin-links` npm flag and other rename operations exacerbate the problem.

**Good news:** This is npm-specific. Users on the native installer, Homebrew, or npx don't see this error. As of January 2026, npm installation is officially deprecated—the native installer is the recommended path forward.
---

## Fix ENOTEMPTY (if you're using npm)

If you haven't seen the exact error `ENOTEMPTY: directory not empty, rename`, skip to the **Troubleshooting** section below to match your specific error. If this is your error, follow these steps:
### For all users (before step 1)

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

```bash
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):

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

**For nvm users specifically**, this expands to:

```bash
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:

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

**For nvm users specifically**:

```bash
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

```bash
npm cache clean --force
```

### Step 4: Reinstall Claude Code globally

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

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

### Fallback 1: --no-bin-links (if reinstall still fails)

If you still hit an ENOTEMPTY error after these steps, try installing with the `--no-bin-links` flag, which bypasses npm's symlink creation (a common trigger for the rename failure on macOS):

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

**Trade-off:** This prevents npm from creating a `claude` symlink in your bin directory. You'll need to either:

1) Invoke the full path:
   ```bash
   node $(npm config get prefix)/lib/node_modules/@anthropic-ai/claude-code/cli.js
   ```

2) Manually create the symlink:
   ```bash
   ln -s $(npm config get prefix)/lib/node_modules/@anthropic-ai/claude-code/bin/claude.js $(npm config get prefix)/bin/claude
   ```

> **Note:** This is a workaround, not a permanent solution. For a hassle-free experience, migrate to the native installer (see below).

---
---

## Fix EACCES: permission denied, mkdir (npm permission errors)

If you see an error like:

```
npm error code EACCES
npm error syscall mkdir
npm error path /usr/local/lib/node_modules/@anthropic-ai
npm error errno -13
npm error Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/...'
```

This means npm is trying to write to a system-protected directory (`/usr/local`). You likely installed Node via an OS installer or Homebrew, which set a global prefix that your user account can't write to.

**Do NOT use sudo.** Instead, either:

### Option 1: Reconfigure npm to use a user-writable directory

```bash
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"  # Add this to ~/.zshrc or ~/.bashrc
```

Then retry the install:

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

### Option 2: Use nvm (Node Version Manager) instead

nvm installs Node and npm in your home directory by default, avoiding system permission issues altogether.

### Option 3: Use the native installer (recommended)

Better yet, skip npm entirely and use the native installer (see below). This avoids permission issues and is the officially recommended path.

---

## Fallback 2: Use npx (temporary workaround)

If both the ENOTEMPTY cleanup and `--no-bin-links` still fail, you can temporarily run Claude Code via npx:

```bash
npx @anthropic-ai/claude-code
```

This bypasses the npm global rename issue entirely because npx doesn't install globally—it fetches the package on-demand and runs it.

### Pros:
- Always runs the latest version
- No global npm conflicts
- Completely sidesteps ENOTEMPTY

### Cons:
- Slower first run (downloads the package)
- Anthropic shows a deprecation notification recommending the native installer
- Not suitable as a long-term solution

Use `npx` only as a short-term workaround while you migrate to the native installer (see below).

---


## Recommended: Migrate to the native installer

The most reliable way to avoid ENOTEMPTY, EACCES, and npm-related issues is to use Anthropic's native installer. **As of January 2026, npm installation is officially deprecated.**

### Install Claude Code via native (recommended)

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

Then ensure the binary is on your PATH:

```bash
export PATH="$HOME/.local/bin:$PATH"  # Add this to ~/.zshrc or ~/.bashrc
```

Verify the install:

```bash
claude --version
```

### Migrate from npm to native (if you already have npm installed)

If you've been using the npm package, switch to native:

1) Install the native version (curl command above)
2) Remove the npm package:
   ```bash
   npm uninstall -g @anthropic-ai/claude-code
   ```
3) Verify you're using the native binary:
   ```bash
   which claude  # Should show ~/.local/bin/claude
   ```

### Why native is better

- **No npm errors:** No ENOTEMPTY, EACCES, or permission issues
- **Auto-updates:** Native automatically updates in the background (npm and Homebrew require manual updates)
- **Works everywhere:** Requires only curl and bash—no Node or npm required
- **Official recommendation:** The path forward endorsed by Anthropic
---

## Troubleshooting: Still hitting errors?

If the above steps don't work, match your error to one of the scenarios below:

### "ENOTEMPTY: directory not empty, rename..."

You're in the right place. Follow the step-by-step fix above. The key is deleting the `.claude-code-*` temp directories—they're what actually trigger the loop. If you still see ENOTEMPTY after the cleanup:

- Verify `npm config get prefix` points to where Claude actually lives: `ls -l $(which claude)`
- Try the `--no-bin-links` fallback above
- Or use `npx @anthropic-ai/claude-code` as a temporary workaround
- Best option: migrate to the native installer (see below)

### "EACCES: permission denied, mkdir..."

See the section "Fix EACCES: permission denied" above. This is a permissions issue, easily resolved by either reconfiguring npm or switching to the native installer.

### "command not found: claude" after native install

Your PATH isn't set. Add this to your `~/.zshrc` or `~/.bashrc`:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

Then restart your terminal and try again.

### Other errors

Run `claude doctor` (native install only) or check the official troubleshooting guide. If you see a different npm error string, paste it into the npm docs (npm.js.org) to understand the underlying issue—it's usually a permissions or network problem unrelated to Claude Code itself.
---

## Summary: Why it happens and how to fix it

The ENOTEMPTY error occurs when npm on macOS (specifically with APFS, extended file attributes, and npm 10+) tries to rename your existing Claude Code installation during an auto-update or reinstall. The rename fails if leftover directories or hidden temp files block the operation—a combination of macOS file-system locking and npm's update mechanism.

**The immediate fix:** Clean up stale directories and reinstall (the steps above).

**The long-term fix:** Use the native installer, which avoids npm entirely. As of January 2026, npm installation is officially deprecated in favor of Anthropic's native installer.

Whichever path you choose—cleanup-and-reinstall or migrate to native—you'll be ready to use Claude Code without update failures.

Let me know in the comments if you've run into other update quirks on macOS, and subscribe for more practical dev fixes.

## LLM Response Snippet
```json
{
  "goal": "Fix Claude Code auto-update failures on macOS Sonoma caused by npm ENOTEMPTY rename errors. Step-by-step: delete old global install, clear npm",
  "responses": [
    {
      "question": "What does the article \"How to Fix Claude Code Failed to Auto-Update on macOS Sonoma (ENOTEMPTY npm Error)\" cover?",
      "answer": "Fix Claude Code auto-update failures on macOS Sonoma caused by npm ENOTEMPTY rename errors. Step-by-step: delete old global install, clear npm"
    }
  ]
}
```