Fix EACCES Permission Errors During npm Install in Claude Code
The Problem
Claude Code runs npm install and hits a permission error:
npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules/some-package
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/some-package'
Or a variation targeting the npm cache:
npm ERR! code EACCES
npm ERR! syscall open
npm ERR! path /Users/you/.npm/_cacache/tmp/some-hash
npm ERR! errno -13
The installation fails, and Claude Code cannot proceed with dependency setup.
Quick Fix
For local project installs, fix the node_modules ownership:
sudo chown -R $(whoami) node_modules/
npm install
For global install permission issues, configure npm to use a user-owned directory:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
What’s Happening
EACCES errors occur when the current user lacks write permission to a directory that npm needs to modify. This happens in three common scenarios:
-
Previous sudo install: Someone ran
sudo npm installat some point, and now root owns files insidenode_modules/. Subsequent non-sudo installs fail because your user cannot write to root-owned directories. -
Global prefix pointing to system directory: npm’s default global prefix (
/usr/local) requires root access on most systems. When Claude Code tries to install a global tool, it fails without sudo. -
Corrupted npm cache: The npm cache directory has mixed ownership from previous sudo operations.
Claude Code runs commands as your current user. It does not use sudo by default (and should not). So any path requiring elevated permissions will trigger EACCES.
Step-by-Step Fix
Step 1: Diagnose the exact cause
Ask Claude Code to identify which path is causing the error:
Run npm install and show me the full error output. Then check
the ownership of the failing path.
Claude Code will run:
npm install 2>&1
ls -la node_modules/ | head -20
ls -la $(npm config get prefix)/lib/node_modules/ 2>/dev/null
Step 2: Fix node_modules ownership (local installs)
If node_modules/ has mixed ownership:
# Check for root-owned files
find node_modules/ -user root -type f | head -10
# Fix ownership recursively
sudo chown -R $(whoami):$(id -gn) node_modules/
# Now install normally
npm install
If node_modules is severely corrupted, remove and reinstall:
rm -rf node_modules package-lock.json
npm install
Step 3: Fix global prefix (global installs)
The recommended approach is to change npm’s global prefix to a user-owned directory:
# Create a dedicated directory
mkdir -p ~/.npm-global
# Tell npm to use it
npm config set prefix '~/.npm-global'
# Add to PATH (for zsh)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
# Verify
npm config get prefix
# Should output: /Users/you/.npm-global
If you use pnpm (which handles this better by default):
pnpm config set global-dir ~/.pnpm-global
pnpm config set global-bin-dir ~/.pnpm-global/bin
Step 4: Fix npm cache permissions
If the npm cache is the problem:
# Check cache location
npm config get cache
# Fix cache ownership
sudo chown -R $(whoami):$(id -gn) ~/.npm
# Or clean the cache entirely
npm cache clean --force
Step 5: Verify the fix
Ask Claude Code to confirm everything works:
Run npm install and verify it completes without permission errors.
Then run npm ls --depth=0 to confirm all dependencies are installed.
Step 6: Handle CI/CD environments
If this happens in CI where Claude Code manages your build pipeline:
# GitHub Actions example - ensure correct permissions
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
In Docker containers, avoid running as root:
FROM node:20-slim
RUN groupadd -r app && useradd -r -g app app
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
USER app
Using pnpm Instead
pnpm avoids most EACCES issues because it uses a content-addressable store in user space:
# Switch to pnpm (no global permission issues)
npm install -g pnpm # last time you need npm for global install
pnpm install
Tell Claude Code to prefer pnpm in your CLAUDE.md:
## Package Management
- Use pnpm, not npm or yarn
- Run `pnpm install` for dependency installation
- Run `pnpm run` for scripts
Prevention
Never run sudo npm install for local project dependencies. If a tutorial tells you to use sudo with npm, it is giving bad advice. The correct fix is always to change ownership or the global prefix.
Add a .npmrc file to your project root to enforce consistent behavior:
engine-strict=true
save-exact=true
fund=false
audit=false
This ensures all team members and CI environments use compatible settings.