Search guides

Fix npm that will not install

We'll check the error, network, and cache—then clear the cache, fix registry URL or proxy—or tell you when to escalate.

Troubleshooting · Devices & software
10–25 min
What you'll need
  • Node.js and npm installed
  • Network access (or proxy config)
Step 1 of 9

Quick triage — pick your path

Get started

Choose the option that matches what you see. You can jump straight to that section.

Show full guide

Steps

Goal: Check the error, network, and cache—then clear the cache, fix registry URL or proxy—or escalate.

  • Run npm install in the project directory. Note the exact error.
  • Good: You see a specific error (connection, ETIMEDOUT, 404, EACCES, ENOSPC). Proceed to Check error and connectivity.
  • Bad: npm hangs—check network connectivity and proxy.

Check error and connectivity

Goal: Confirm the error and test registry reachability.

  • Run npm config get registry to see the configured registry URL.
  • Test with curl -I https://registry.npmjs.org or ping registry.npmjs.org. If unreachable, check proxy (npm config proxy or HTTP_PROXY, HTTPS_PROXY) or firewall.
  • Run df -h (Linux/macOS) or check drive space (Windows). npm needs space for node_modules and cache.
  • Good: Registry is reachable and disk has space. Proceed to Fix cache and registry.
  • Bad: Registry unreachable or disk full—fix the registry URL, proxy, or free space first.

Fix cache and registry

Goal: Clear corrupted cache and fix wrong registry URL.

  • Run npm cache clean --force to clear the npm cache. Retry npm install.
  • If the registry URL is wrong, run npm config set registry https://registry.npmjs.org. For a private registry, use the correct URL.
  • If the error persists, delete node_modules and package-lock.json. Run npm install again.
  • Good: Install succeeds. Bad: Try a different network or disable VPN; if still failing, escalate.

When to escalate

Escalate if:

  • The registry is managed by a central team and you cannot change it.
  • The proxy or firewall blocks npm and you cannot change it.
  • The fix requires infrastructure changes outside your control.

Provide: the npm error, npm config list output, and result of curl -I to the registry URL.

Verification

  • npm install completes without errors.
  • The node_modules folder exists and contains the expected packages.
  • No connection, cache, or permission errors in the output.

Escalation ladder

Work from the device outward. Stop when the problem is fixed.

  1. Capture error Run npm install; note exact error.
  2. Connectivity and disk Test registry URL with curl; check disk space.
  3. Cache and registry npm cache clean --force; set correct registry.
  4. Clean reinstall Delete node_modules and package-lock; npm install.
  5. Escalate Enterprise-managed registry or infrastructure change needed.

What to capture if you need help

Before calling support or posting for help, have these ready. It speeds everything up.

  • Exact npm error message
  • Output of npm config list
  • Result of curl -I to registry URL
  • Disk space (df -h or equivalent)

Does npm install show a specific error?

Run npm install and note the error: connection, ETIMEDOUT, 404, EACCES, or ENOSPC.

Run `npm install`. Good: You see a specific error (connection refused, ETIMEDOUT, 404, EACCES, ENOSPC). Bad: npm hangs with no output—check network connectivity.

Yes No (hangs)

You can change your answer later.

Check connectivity and timeouts

Test registry with `curl -I https://registry.npmjs.org` or `ping registry.npmjs.org`. If unreachable, check proxy (npm config proxy or HTTP_PROXY) or firewall. Check disk space.

Done

Can you reach the registry URL?

Test with curl -I. Registry must return HTTP 200.

Run `npm config get registry` and test with `curl -I <registry-url>`. Good: HTTP 200 or host reachable. Bad: Timeout or 404—fix registry URL or proxy.

Yes No

You can change your answer later.

Fix registry URL and retry

Set correct registry: `npm config set registry https://registry.npmjs.org`. For private registry, use the correct URL. Retry `npm install`.

Done

Is disk space sufficient?

npm needs space for node_modules and cache.

Run `df -h` (Linux/macOS) or check drive space. Good: At least a few percent free. Bad: Near 100%—free space first.

Yes No

You can change your answer later.

Clear cache and retry

Corrupted cache causes odd failures.

Run `npm cache clean --force`. Retry `npm install`. Good: Install succeeds. Bad: Delete node_modules and package-lock.json, then npm install again.

Yes No

You can change your answer later.

Install succeeded

npm install completed. Check that node_modules exists and the app runs.

Done

Delete node_modules and retry

Delete `node_modules` and `package-lock.json`. Run `npm install` again. npm will rebuild from package.json.

Done

Escalate

Escalate if the registry is enterprise-managed, you cannot change proxy or firewall, or disk cannot be expanded. Provide npm error, npm config list output, and curl test results.

Done

Reviewed by Blackbox Atlas

Frequently asked questions

Why would npm install fail?
Network unreachable, wrong or unreachable registry URL, corrupted cache, full disk, or permission denied. Check the error message first.
Can I fix npm install myself?
Yes. Check connectivity, registry URL, and cache. Clear cache with npm cache clean --force, set correct registry, or use a different network. For permission errors, avoid global installs or fix ownership.
When should I escalate npm install failures?
If the registry is enterprise-managed and you cannot change it, or the fix requires proxy or firewall changes outside your control.

Rate this guide

Was this helpful?

Continue to