npm install times out or never finishes
ETIMEDOUTShort 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.
Fix it fast
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-proxy2Match what you see, then jump to its fix
- 1
ETIMEDOUT that comes and goes; a second run gets furtherThe connection is slow and npm runs out of retriesFix - 2
ETIMEDOUT every time on a company or school network, while a browser worksThe network needs a proxy and npm was not told about itFix - 3
ETIMEDOUT against a host that is not registry.npmjs.orgThe registry setting points at an address you cannot reachFix - 4
The install stops at addRemoteTarball and never moves onOn Windows, npm hangs because the tmp setting appears more than onceFix
- 1
What does the error look like?
ETIMEDOUTnpm install does not finish and prints nothing for minutesnpm 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-timeout2Fix
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 6000003Verify
Run the install with verbose output and watch it pass the step that failed.
npm install --verboseConfirmed by docs.npmjs.com
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:80803Verify
Ask the registry for one package's version.
npm view express versionConfirmed by docs.npmjs.com
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 list2Fix
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 versionConfirmed by docs.npmjs.com
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 -l2Fix
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 -l3Verify
Only one tmp line is shown and the install finishes.
npm installConfirmed by docs.npmjs.com
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
Servers
npm and yarn are many times slower in WSL than on plain Windows
pwd prints /mnt/c/Users/...
Almost always the project lives on the Windows drive (/mnt/c), and every file read crosses between the two systems.
2 causes, each with a fixBack 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 fixBack end
Application Load Balancer returns 502 for a Node.js target
HTTPCode_ELB_502_Count
An ALB returns 502 when the target gives it something it cannot use: a refused or reset connection, a connection closed mid-request, a bad response, or a header over 32 K.
4 causes, each with a fixBack end
corepack enable fails: permission denied while creating the pnpm link
Internal Error: EACCES: permission denied, symlink '../lib/node_modules/corepack/dist/pnpm.js' -> '/usr/local/bin/pnpm'
corepack enable writes small link files for yarn and pnpm next to your node binary.
2 causes, each with a fixBack end
Create React App says Node is too old, and npm will not run on the new one
npm does not support Node.js v10.19.0
The shell is running an old Node.js that is below the version Create React App needs.
3 causes, each with a fixBack end
firebase deploy cannot load your functions: user code failed to load
Functions codebase could not be analyzed successfully. It may have a syntax or runtime error
The Firebase CLI loads your functions code on your machine before it deploys, to learn which functions exist.
4 causes, each with a fix