Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

npm install times out or never finishes

ErrorETIMEDOUT

Short answer

npm install waits for the registry, retries a few times, then gives up. So a timeout means the request never got through: a slow link that needs more retries, a company proxy npm does not know about, a registry setting that points somewhere unreachable, or on Windows a duplicated tmp setting. Check the registry value first.

  • Applies to npm 10 and 11, Node.js 22 and 24, Windows 11, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the registry and proxy values npm really uses. A wrong or unreachable address here explains most timeouts.

    npm config get registry
    npm config get proxy
    npm config get https-proxy
  2. 2Match what you see, then jump to its fix

    1. 1ETIMEDOUT that comes and goes; a second run gets furtherThe connection is slow and npm runs out of retriesFix
    2. 2ETIMEDOUT every time on a company or school network, while a browser worksThe network needs a proxy and npm was not told about itFix
    3. 3ETIMEDOUT against a host that is not registry.npmjs.orgThe registry setting points at an address you cannot reachFix
    4. 4The install stops at addRemoteTarball and never moves onOn Windows, npm hangs because the tmp setting appears more than onceFix

What does the error look like?

  • ETIMEDOUT
  • npm install does not finish and prints nothing for minutes
  • npm hangs at addRemoteTarball on Windows

Cause 1 of 4

The connection is slow and npm runs out of retries

1Check

npm retries read requests that fail on the network or return a 5xx error. The defaults are 2 retries, a 10 second minimum wait between them and a 5 minute request timeout, which a weak connection can use up.

npm config get fetch-retries
npm config get fetch-timeout

2Fix

Give npm more retries and more time between them, then run the install again.

npm config set fetch-retries 5
npm config set fetch-retry-maxtimeout 120000
npm config set fetch-timeout 600000

3Verify

Run the install with verbose output and watch it pass the step that failed.

npm install --verbose

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 4

The network needs a proxy and npm was not told about it

1Check

npm only uses a proxy that is set in its config or in the HTTP_PROXY and HTTPS_PROXY environment variables. If proxy and https-proxy print null and the variables are empty, npm tries to connect directly.

npm config get https-proxy
echo "$HTTPS_PROXY"

2Fix

Set the proxy address your network team gave you, for both plain and TLS requests.

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

3Verify

Ask the registry for one package's version.

npm view express version

Confirmed by docs.npmjs.com

Did this fix it?

Cause 3 of 4

The registry setting points at an address you cannot reach

1Check

The registry setting is the base URL for every request. An old mirror or a company registry left in a user or project .npmrc sends all traffic there. The default is https://registry.npmjs.org/.

npm config get registry
npm config list

2Fix

Remove the stale line from the .npmrc that sets it, or set the registry back to the default.

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

3Verify

Check that the value is the default and that a lookup works.

npm config get registry
npm view express version

Confirmed by docs.npmjs.com

Did this fix it?

Cause 4 of 4

On Windows, npm hangs because the tmp setting appears more than once

1Check

npm's error guide says to list the full config and look at the tmp lines. If more than one appears, npm can hang.

npm config ls -l

2Fix

Keep one tmp setting and remove the extra ones from your .npmrc files, then run the install again.

# edit the .npmrc files that set tmp so only one line is left
npm config ls -l

3Verify

Only one tmp line is shown and the install finishes.

npm install

Confirmed by docs.npmjs.com

Did this fix it?

How do I stop it coming back?

  • Keep proxy settings in one place per machine, not copied between project .npmrc files.
  • Commit the lockfile and use npm ci in CI so every run asks the registry for exactly the same files.
  • Run npm install with --verbose when a step looks stuck, so you see which URL it waits on.
  • Check status.npmjs.com before changing local settings when only the registry seems slow.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

npm rejects the certificate it gets from a company proxy

npm ERR! request to https://registry.npmjs.org/express failed, reason: self signed certificate in certificate chain

A proxy that inspects HTTPS traffic re-signs it with the company's own root certificate, which Node does not know, so npm refuses the connection.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.