npm ERR! network: How to Fix npm Install Timeouts with a Registry Mirror

Symptom: npm install hangs or fails with network errors

The classic trio on constrained networks:

npm ERR! network request to https://registry.npmjs.org/xxx failed
npm ERR! network This is a problem related to network connectivity.
npm ERR! network ETIMEDOUT / ECONNRESET / ERR_SOCKET_CONNECTION_TIMEOUT

npm defaults to the official registry (registry.npmjs.org, a CDN outside many regions) which can be slow or unreachable. Work through the fixes in order — most cases resolve at step one.

Step one: switch to a fast registry mirror

# Check current registry
npm config get registry
# Switch to npmmirror (the China mirror, formerly taobao)
npm config set registry https://registry.npmmirror.com
# Verify
npm config get registry
# https://registry.npmmirror.com

npmmirror syncs with the official registry at minute-level frequency — more than enough for daily development. Re-run npm install to verify.

One-off use (without changing global config, e.g. when publishing):

npm install --registry=https://registry.npmmirror.com

Step two: clean the cache (if the error persists after switching)

npm's local cache may hold failed responses:

npm cache clean --force
npm cache verify
npm install

Step three: hunt stale proxy configs

If a proxy was configured before (by you, a colleague, or a tool) and the proxy is now dead, npm keeps sending requests to it — symptoms identical to a direct-connection timeout:

npm config list         # look for proxy / https-proxy / odd registry
npm config delete proxy
npm config delete https-proxy
# Env vars affect npm too (HTTP_PROXY / HTTPS_PROXY / NO_PROXY)
env | grep -i proxy

Classic trap: you configured a proxy at the office and forgot to remove it at home; or your VPN client sets a system proxy that npm ignores (npm only reads its own config and env vars). For VPN tools like Clash: either enable TUN mode (global takeover) or point npm at the local proxy port (usually proxy=http://127.0.0.1:7890).

Step four: the package-lock trap

package-lock.json records the registry URL used at install time (the resolved fields). If the lock file was generated on another machine with a different registry, those resolved URLs may point somewhere you can't reach:

# Inspect where resolved points
grep -m3 '"resolved"' package-lock.json
# If it points to a broken source: delete the lock and reinstall
# (note: dependency versions may bump; teams must re-commit the lock)
rm package-lock.json node_modules -rf
npm install

Team note: lock files belong in git; the registry decision should be team-wide (or committed as a project .npmrc — see below).

Long term: project-level .npmrc

Put a .npmrc in the repo root and commit it — teammates get the same registry on clone:

registry=https://registry.npmmirror.com

One caveat: if the team publishes packages to npm, publishing needs a one-off --registry=https://registry.npmjs.org (npmmirror is a read-only mirror).

FAQ

yarn / pnpm are also slow — same fix?

Yes, each has its own config system:

yarn config set registry https://registry.npmmirror.com
pnpm config set registry https://registry.npmmirror.com

pnpm also reads a project .npmrc (shared with npm).

Some packages still download from the official registry?

Some packages resolve to GitHub Releases or bundled downloaders (puppeteer's Chromium, sharp's prebuilt binaries) — those bypass the registry entirely. Targeted fixes: set the package's own mirror env var (e.g. PUPPETEER_DOWNLOAD_BASE_URL) or skip the download (PUPPETEER_SKIP_DOWNLOAD=true).

Does the mirror ever miss packages or versions?

No. npmmirror is a syncing mirror of the official registry (minute-level sync) with full version fidelity. Only brand-new publishes have minutes of lag.

npm's problem or my network's?

curl -I https://registry.npmmirror.com   # 200 = mirror reachable
curl -I https://registry.npmjs.org       # is the official registry reachable

Mirror reachable but official not → switching solves it. Both unreachable → check local network, DNS, or firewall.

Provided by ToolVault. Related tools: Linux Cheatsheet, Dockerfile Generator, HTTP Status Codes. See the homepage for more developer tools.