npm install Not Working— Every Fix [Complete Guide 2026]
⚡ 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 installWindows? 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... | Cause | Fix |
|---|---|---|
| ENOENT, cache error, idealTree | Corrupted cache or lock file | Jump → |
| ENOTFOUND, network, ETIMEDOUT | Network or registry unreachable | Jump → |
| EACCES, permission denied | File permission issue | Jump → |
| Hangs, no output, stuck | Network timeout or lock file | Jump → |
| ERESOLVE, peer dependency | Dependency version conflict | Jump → |
| EBADENGINE, engine mismatch | Wrong Node.js version | Jump → |
| ECONNREFUSED, proxy error | Corporate proxy blocking npm | Jump → |
| ENOSPC, out of disk space | Disk or memory full | Jump → |
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.
Clear Cache + Delete node_modules
Corrupted cache · idealTree errors · stale lock fileThe 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
npm cache clean --force
rm -rf node_modules package-lock.json
npm installWindows — Command Prompt
npm cache clean --force
rmdir /s /q node_modules
del package-lock.json
npm installWindows — PowerShell
npm cache clean --force
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm installClearing 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.
Network and Registry Issues
ENOTFOUND · ETIMEDOUT · registry errorsIf 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
# Can you reach the npm registry?
ping registry.npmjs.org
# What registry is npm pointing to?
npm config get registryRegistry is wrong — reset to default
If the registry shows something other than https://registry.npmjs.org/, a previous tool changed it. Reset:
npm config set registry https://registry.npmjs.org/Try installing with verbose output
npm install --verboseSwitch to a registry mirror
If the main registry is slow or down in your region, try a mirror temporarily:
# 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
npm config set prefer-ipv4 trueIf 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.
Permission Errors (EACCES)
EACCES · permission denied · sudo issuesnpm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules
npm ERR! errno -13
npm ERR! Error: EACCES: permission deniedThis 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
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}Fix project node_modules ownership
sudo chown -R $(whoami) node_modules
rm -rf node_modules package-lock.json
npm installWindows — 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.
npm install Stuck or Hanging Forever
No output · cursor blinking · never completesnpm 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
# Press Ctrl+C to cancel the stuck install
# Then check versions
node --version
npm --versionStep 2 — Try with verbose flag
npm install --verbose
# Watch where it stops — that line is the problemStep 3 — Clear cache and use prefer-offline
npm cache clean --force
npm install --prefer-offlineStep 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:
npm install --fetch-timeout=120000 # 2 minutes
npm install --fetch-retry-mintimeout=20000
npm install --fetch-retry-maxtimeout=120000Step 5 — Check for a hung npm process
ps aux | grep npm
pkill -f npmGet-Process | Where-Object { $_.Name -like "*node*" }
Stop-Process -Name "node" -ForceAntivirus 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.
Peer Dependency Conflicts (ERESOLVE)
ERESOLVE · unable to resolve dependency treenpm 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.0This 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)
npm install --legacy-peer-depsOption B — Force install (use with caution)
npm install --forceOption 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:
legacy-peer-deps=trueOption D — Update the conflicting package
# Update the package causing the peer conflict
npm install some-package@latest
# Or check what version supports your react version
npm info some-package peerDependenciesUsing --force can install genuinely incompatible versions that crash at runtime rather than install time. Always test your app after a forced install.
Node / npm Version Mismatch (EBADENGINE)
EBADENGINE · wrong Node versionSome 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
node --version # should be 18.x or higher in 2026
npm --version # should be 9.x or 10.xUpdate Node with nvm
nvm install --lts
nvm use --lts
nvm alias default node
# Retry install
npm installBypass engine check temporarily
npm install --engine-strict=falseCheck the engines field of the failing package: 'npm info package-name engines'. This tells you exactly what Node version it needs.
Proxy and Corporate Network Issues
ECONNREFUSED · self-signed certificate · corporate firewallCorporate 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
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080Fix self-signed certificate errors
# 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 falseCheck all current npm proxy settings
npm config list
# Look for proxy, https-proxy, registry, cafile entriesRemove proxy settings (if set incorrectly)
npm config delete proxy
npm config delete https-proxySetting strict-ssl=false disables certificate validation entirely. Only use this as a last resort in a development environment — never in production CI/CD pipelines.
Disk Space and Memory Issues (ENOSPC)
ENOSPC · out of disk · JavaScript heap out of memorynpm ERR! code ENOSPC
npm ERR! syscall write
npm ERR! errno -28
npm ERR! ENOSPC: no space left on devicenpm 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
df -hGet-PSDrive CClear npm cache to free space
npm cache clean --force
# See how much space the cache is using
du -sh ~/.npmJavaScript heap out of memory
For very large projects, npm can run out of memory during install. Increase Node's available heap:
# Increase to 4GB
node --max-old-space-size=4096 $(which npm) install
# macOS / Linux shorthand
NODE_OPTIONS=--max-old-space-size=4096 npm installNuclear Option — Full npm Reset
When nothing else has workedIf every fix above has failed, the npm installation itself is broken. This full reset wipes all npm state and starts from scratch.
macOS / Linux
# 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 installWindows
# 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 installOS-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.
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 --ltsWindows
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:
# 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.
# In GitHub Actions, GitLab CI, Jenkins etc.
npm ci # faster + deterministic + strict lock file check
# vs
npm install # slower + may update package-lock.jsonComplete Fix Checklist — Work Through in Order
- 1
Read the exact error code in your terminal
Match it to the diagnosis table above
- 2
Clear cache + delete node_modules + reinstall
npm cache clean --force && rm -rf node_modules package-lock.json && npm install
- 3
Check internet + verify registry URL
npm config get registry → reset if wrong
- 4
Fix permission errors
sudo chown -R $(whoami) ~/.npm
- 5
Kill any stuck npm processes
pkill -f npm (macOS/Linux)
- 6
Resolve peer dependency conflicts
npm install --legacy-peer-deps
- 7
Update Node to LTS via nvm
nvm install --lts && nvm use --lts
- 8
Configure proxy settings if on corporate network
npm config set proxy http://...
- 9
Check disk space
df -h (macOS/Linux)
- 10
Nuclear reset — wipe everything, reinstall via nvm
See Fix 9
Frequently Asked Questions
Why is npm install not working?+−
npm install is stuck and not doing anything — what do I do?+−
How do I fix npm install EACCES permission denied?+−
npm install says unable to resolve dependency tree — how do I fix it?+−
npm install works locally but fails in CI — why?+−
How do I speed up npm install?+−
npm install keeps deleting and re-adding packages — what is happening?+−
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