npmNode.jsTroubleshooting2026 Updated

npm install Not Working— Every Fix [Complete Guide 2026]

January 20269 min readnpm 9–10 · Node 18–22 · All OS

⚡ Try This First — Fixes 70% of Cases

Three commands. Run them in order:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Windows? Use rmdir /s /q node_modules && del package-lock.json instead of the rm line.

Still broken? The problem is one of nine specific causes. The next section will identify yours in under a minute.

Read the Error First — Diagnose in 30 Seconds

npm install not working is a symptom, not a cause. The terminal output tells you exactly what is wrong — if you know what to look for. Find your error type below and jump straight to the right fix.

Error Message → Cause → Jump to Fix

Error contains...CauseFix
ENOENT, cache error, idealTreeCorrupted cache or lock fileJump →
ENOTFOUND, network, ETIMEDOUTNetwork or registry unreachableJump →
EACCES, permission deniedFile permission issueJump →
Hangs, no output, stuckNetwork timeout or lock fileJump →
ERESOLVE, peer dependencyDependency version conflictJump →
EBADENGINE, engine mismatchWrong Node.js versionJump →
ECONNREFUSED, proxy errorCorporate proxy blocking npmJump →
ENOSPC, out of disk spaceDisk or memory fullJump →

Run npm install with verbose logging to get the most detail: 'npm install --verbose'. This shows exactly which step failed and why — much easier to diagnose than the default output.

1

Clear Cache + Delete node_modules

Corrupted cache · idealTree errors · stale lock file
2–5 min

The most common cause of a suddenly broken npm install is a corrupted cache or a package-lock.json that has drifted out of sync with the registry. This clears everything and starts fresh.

macOS / Linux

terminal
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Windows — Command Prompt

cmd
npm cache clean --force
rmdir /s /q node_modules
del package-lock.json
npm install

Windows — PowerShell

powershell
npm cache clean --force
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install

Clearing the npm cache does not delete your installed packages or your source code. It only removes cached package tarballs. Completely safe to run at any time.

2

Network and Registry Issues

ENOTFOUND · ETIMEDOUT · registry errors
2–5 min

If npm cannot reach the registry at registry.npmjs.org, every install will fail. This can be caused by no internet connection, DNS issues, a misconfigured registry URL, or VPN interference.

Check your internet and registry

terminal
# Can you reach the npm registry?
ping registry.npmjs.org

# What registry is npm pointing to?
npm config get registry

Registry is wrong — reset to default

If the registry shows something other than https://registry.npmjs.org/, a previous tool changed it. Reset:

terminal
npm config set registry https://registry.npmjs.org/

Try installing with verbose output

terminal
npm install --verbose

Switch to a registry mirror

If the main registry is slow or down in your region, try a mirror temporarily:

terminal
# Cloudflare npm mirror (fast globally)
npm install --registry https://registry.npmjs.cf/

# Or use npmmirror (popular in Asia)
npm install --registry https://registry.npmmirror.com/

Disable IPv6 if causing DNS issues

terminal
npm config set prefer-ipv4 true

If you are on VPN, try disconnecting it and running npm install again. VPNs frequently intercept HTTPS traffic to the npm registry and cause ENOTFOUND or ETIMEDOUT errors without any obvious indication.

3

Permission Errors (EACCES)

EACCES · permission denied · sudo issues
2 min
Terminal Error
npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied

This means npm is trying to write to a directory it does not have permission to modify. The most common cause on macOS and Linux is that node_modules or the npm cache is partially owned by root from a previous sudo npm install.

Never use 'sudo npm install' for local project packages. It creates root-owned files that break all future non-sudo installs. If you are using sudo because npm demands it, the real fix is fixing the ownership — not escalating privileges.

Fix npm cache ownership — macOS / Linux

terminal
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

Fix project node_modules ownership

terminal
sudo chown -R $(whoami) node_modules
rm -rf node_modules package-lock.json
npm install

Windows — run terminal as Administrator

Right-click Command Prompt or PowerShell → Run as Administrator → retry npm install. For a permanent fix without admin access every time, use nvm-windows which installs Node in your user profile directory.

The permanent fix for permission issues on macOS and Linux is to use nvm. It installs Node in your home directory (~/.nvm) where you always have full write access — no sudo required, ever.

4

npm install Stuck or Hanging Forever

No output · cursor blinking · never completes
3 min

npm install hangs at a blank cursor with zero output — no error, no progress. This is one of the most frustrating scenarios and has several distinct causes.

Step 1 — Cancel and check npm version

terminal
# Press Ctrl+C to cancel the stuck install
# Then check versions
node --version
npm --version

Step 2 — Try with verbose flag

terminal
npm install --verbose
# Watch where it stops — that line is the problem

Step 3 — Clear cache and use prefer-offline

terminal
npm cache clean --force
npm install --prefer-offline

Step 4 — Increase network timeout

npm defaults to a 30-second network timeout. On slow connections or large packages, this can cause installs to silently hang:

terminal
npm install --fetch-timeout=120000   # 2 minutes
npm install --fetch-retry-mintimeout=20000
npm install --fetch-retry-maxtimeout=120000

Step 5 — Check for a hung npm process

macOS / Linux
ps aux | grep npm
pkill -f npm
Windows PowerShell
Get-Process | Where-Object { $_.Name -like "*node*" }
Stop-Process -Name "node" -Force

Antivirus real-time scanning of node_modules is a common silent cause of hanging installs on Windows. Add your project folder to your antivirus exclusion list and the hang will often disappear immediately.

5

Peer Dependency Conflicts (ERESOLVE)

ERESOLVE · unable to resolve dependency tree
2 min
Terminal Error
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: my-app@1.0.0
npm ERR! Found: react@18.2.0
npm ERR! node_modules/react
npm ERR!   react@"^18.2.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from some-package@2.1.0

This means two packages in your dependency tree require incompatible versions of the same package. npm 7+ introduced strict peer dependency resolution which surfaces these conflicts as hard errors rather than silently installing the wrong version.

Option A — Use legacy peer deps (quickest)

terminal
npm install --legacy-peer-deps

Option B — Force install (use with caution)

terminal
npm install --force

Option C — Make it permanent in .npmrc

If your project consistently requires --legacy-peer-deps, add it to .npmrc so you never need to type it again:

.npmrc
legacy-peer-deps=true

Option D — Update the conflicting package

terminal
# Update the package causing the peer conflict
npm install some-package@latest

# Or check what version supports your react version
npm info some-package peerDependencies

Using --force can install genuinely incompatible versions that crash at runtime rather than install time. Always test your app after a forced install.

6

Node / npm Version Mismatch (EBADENGINE)

EBADENGINE · wrong Node version
3 min

Some packages require a minimum Node.js version to install correctly. If your Node version is too old, npm install will fail with an engine compatibility warning or error.

Check your versions

terminal
node --version    # should be 18.x or higher in 2026
npm --version     # should be 9.x or 10.x

Update Node with nvm

terminal
nvm install --lts
nvm use --lts
nvm alias default node

# Retry install
npm install

Bypass engine check temporarily

terminal
npm install --engine-strict=false

Check the engines field of the failing package: 'npm info package-name engines'. This tells you exactly what Node version it needs.

7

Proxy and Corporate Network Issues

ECONNREFUSED · self-signed certificate · corporate firewall
5 min

Corporate networks often route traffic through a proxy or use SSL inspection that breaks npm's certificate validation. This causes ECONNREFUSED, UNABLE_TO_GET_ISSUER_CERT_LOCALLY, or silent hangs.

Configure npm to use your corporate proxy

terminal
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

Fix self-signed certificate errors

terminal
# Tell npm where the corporate CA cert is
npm config set cafile /path/to/corporate-cert.pem

# Or — less secure — disable strict SSL (dev only)
npm config set strict-ssl false

Check all current npm proxy settings

terminal
npm config list
# Look for proxy, https-proxy, registry, cafile entries

Remove proxy settings (if set incorrectly)

terminal
npm config delete proxy
npm config delete https-proxy

Setting strict-ssl=false disables certificate validation entirely. Only use this as a last resort in a development environment — never in production CI/CD pipelines.

8

Disk Space and Memory Issues (ENOSPC)

ENOSPC · out of disk · JavaScript heap out of memory
5 min
Terminal Error
npm ERR! code ENOSPC
npm ERR! syscall write
npm ERR! errno -28
npm ERR! ENOSPC: no space left on device

npm install writes package files to disk. If your disk is nearly full, the install will fail mid-way with ENOSPC. Large projects with many dependencies can require several gigabytes of free space.

Check available disk space

macOS / Linux
df -h
Windows PowerShell
Get-PSDrive C

Clear npm cache to free space

terminal
npm cache clean --force

# See how much space the cache is using
du -sh ~/.npm

JavaScript heap out of memory

For very large projects, npm can run out of memory during install. Increase Node's available heap:

terminal
# Increase to 4GB
node --max-old-space-size=4096 $(which npm) install

# macOS / Linux shorthand
NODE_OPTIONS=--max-old-space-size=4096 npm install
9

Nuclear Option — Full npm Reset

When nothing else has worked
10 min

If every fix above has failed, the npm installation itself is broken. This full reset wipes all npm state and starts from scratch.

macOS / Linux

terminal
# 1. Clear all npm caches
npm cache clean --force
rm -rf ~/.npm

# 2. Remove project dependencies
rm -rf node_modules package-lock.json

# 3. Reinstall Node with nvm (clean install)
nvm install --lts
nvm use --lts
nvm alias default node

# 4. Fresh project install
npm install

Windows

powershell (Administrator)
# 1. Clear caches
npm cache clean --force
Remove-Item -Recurse -Force "$env:APPDATA
pm-cache"

# 2. Remove project dependencies
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json

# 3. Reinstall via nvm-windows
# Download nvm-windows from github.com/coreybutler/nvm-windows
nvm install lts
nvm use lts

# 4. Fresh install
npm install

OS-Specific Notes

macOS

The most common macOS-specific issues are permission errors from previous sudo npm install usage, and Homebrew upgrading Node without updating npm. If you are on macOS, the single best thing you can do is uninstall Homebrew Node and switch entirely to nvm. It eliminates almost every recurring npm install issue.

terminal
brew uninstall node
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.zshrc
nvm install --lts && nvm use --lts

Windows

Windows-specific causes that rarely appear on Mac or Linux: antivirus real-time scanning of node_modules (causes hangs), long path limit of 260 characters (breaks deep dependency trees), and multiple conflicting Node installations from different package managers. Enable long paths and use nvm-windows:

PowerShell (Administrator)
# Enable Windows long path support
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

# Add project folder to Defender exclusions to stop antivirus hanging installs
Add-MpPreference -ExclusionPath "C:\path\to\your\project"

Linux / CI environments

In CI pipelines and Linux servers, use npm ci instead of npm install. It is faster, more deterministic, and fails loudly if package-lock.json is out of sync — catching problems in CI before they reach production.

CI pipeline
# In GitHub Actions, GitLab CI, Jenkins etc.
npm ci          # faster + deterministic + strict lock file check

# vs
npm install     # slower + may update package-lock.json

Complete Fix Checklist — Work Through in Order

  1. 1

    Read the exact error code in your terminal

    Match it to the diagnosis table above

  2. 2

    Clear cache + delete node_modules + reinstall

    npm cache clean --force && rm -rf node_modules package-lock.json && npm install

  3. 3

    Check internet + verify registry URL

    npm config get registry → reset if wrong

  4. 4

    Fix permission errors

    sudo chown -R $(whoami) ~/.npm

  5. 5

    Kill any stuck npm processes

    pkill -f npm (macOS/Linux)

  6. 6

    Resolve peer dependency conflicts

    npm install --legacy-peer-deps

  7. 7

    Update Node to LTS via nvm

    nvm install --lts && nvm use --lts

  8. 8

    Configure proxy settings if on corporate network

    npm config set proxy http://...

  9. 9

    Check disk space

    df -h (macOS/Linux)

  10. 10

    Nuclear reset — wipe everything, reinstall via nvm

    See Fix 9

Frequently Asked Questions

Why is npm install not working?+
npm install can fail for many reasons: corrupted cache, wrong directory, network issues, permission errors, Node/npm version mismatch, peer dependency conflicts, disk space exhaustion, or a corporate proxy blocking registry access. The best first step is to read the exact error message in your terminal — it tells you which category of problem you are dealing with.
npm install is stuck and not doing anything — what do I do?+
A stuck npm install is almost always a network issue or a lock file conflict. Try: press Ctrl+C to cancel, run 'npm cache clean --force', then retry with 'npm install --prefer-offline'. If it hangs again, check your internet connection, disable VPN if active, and try switching to a different npm registry mirror.
How do I fix npm install EACCES permission denied?+
Never use sudo with npm install for local packages — it creates files owned by root that cause future permission errors. Instead, fix the ownership of your npm cache: 'sudo chown -R $(whoami) ~/.npm' on macOS/Linux. On Windows, run your terminal as Administrator or use nvm-windows which avoids permission issues entirely.
npm install says unable to resolve dependency tree — how do I fix it?+
This is a peer dependency conflict. Run 'npm install --legacy-peer-deps' to use the older, more permissive resolver that ignores peer dependency conflicts. Alternatively run 'npm install --force' but be aware this may install incompatible versions.
npm install works locally but fails in CI — why?+
The most common CI-specific causes are: different Node version in CI than locally (fix with .nvmrc or actions/setup-node), missing package-lock.json in the repo (always commit it), network restrictions blocking the npm registry, or insufficient memory in the CI container for large installs.
How do I speed up npm install?+
Use 'npm ci' instead of 'npm install' in CI environments — it is faster and more deterministic. Use '--prefer-offline' to use cached packages when possible. Consider switching to pnpm which uses a global content-addressable store and is significantly faster than npm for large monorepos.
npm install keeps deleting and re-adding packages — what is happening?+
This usually means your package-lock.json is out of sync with package.json, often caused by a git merge conflict that was not fully resolved. Delete package-lock.json and node_modules, then run npm install to generate a fresh, consistent lock file.

Need Expert Help?

We Build Production-Grade Next.js & Node.js Apps

Softplix is a full-stack development agency. Stuck on npm issues in a production project? We can audit your setup and get you shipping again.

Talk to an Engineer