How to fix npm ERR! code ETIMEDOUT npm ERR! network request to https://registry.npmjs.org timed out in npm

npmBEGINNERMEDIUMUpdated Dec 6, 2025· 351 views

This error occurs when npm cannot establish a connection to the registry within the timeout period (default 30 seconds). Common causes include IPv6 connectivity issues, proxy misconfiguration, firewall restrictions, or slow network conditions.

Quick fix

Fixes ETIMEDOUT

# Set prefer-ip-version to 4 in npm config
npm config set prefer-ip-version 4
  1. Disable IPv6 to force IPv4 connections
  2. Increase npm timeout settings
  3. Check and configure proxy settings
  4. Clear npm cache and delete package-lock.json
npm — error
# Set prefer-ip-version to 4 in npm config
npm config set prefer-ip-version 4
npm ERR! code ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org timed out

What this error means

The ETIMEDOUT error in npm indicates that a network request to the npm registry (or a private registry) failed because it took too long to complete. By default, npm waits 30 seconds for a response before timing out. When you run `npm install`, npm connects to the registry to fetch package metadata and tarballs. If the connection cannot be established or the response takes too long, you'll see this timeout error. The issue is almost always network-related rather than a problem with npm itself. This error has become increasingly common since Node.js 18+, which defaults to IPv6 connections. Many networks and ISPs don't properly support IPv6, causing connections to hang before falling back to IPv4 - often exceeding the timeout limit. Other causes include corporate proxies, VPN interference, firewall rules blocking outbound connections, or simply slow/unstable internet.

Typical symptoms

  • npm install hangs for 30+ seconds before failing with ETIMEDOUT
  • Error consistently occurs on specific networks (home, office, VPN)
  • npm commands work on one machine but timeout on another
  • Fresh Node.js 18+ installation starts having timeout issues
  • npm works intermittently - sometimes succeeds, sometimes times out
  • CI/CD pipelines fail with ETIMEDOUT after previously working

Common causes

  1. IPv6 connectivity issues (most common in Node.js 18+ where IPv6 is preferred)
  2. Corporate proxy misconfiguration or missing proxy settings in npm
  3. Firewall blocking outbound connections to registry.npmjs.org on port 443
  4. VPN software interfering with DNS resolution or routing
  5. Default timeout (30s) too short for slow network conditions
  6. Docker or WSL2 networking issues with host network connectivity
  7. DNS resolution delays causing connection to exceed timeout
  8. Network congestion or unstable internet connection

How to fix "npm ERR! code ETIMEDOUT npm ERR! network request to https://registry.npmjs.org timed out"

1Disable IPv6 to force IPv4 connections

The most common cause of ETIMEDOUT on Node.js 18+ is IPv6 connectivity issues. Force npm to use IPv4:

bash
# Set prefer-ip-version to 4 in npm config
npm config set prefer-ip-version 4

Or set it globally via environment variable:

bash
# Linux/macOS - add to ~/.bashrc or ~/.zshrc
export NODE_OPTIONS="--dns-result-order=ipv4first"

# Windows PowerShell
$env:NODE_OPTIONS="--dns-result-order=ipv4first"

Then retry your npm command:

bash
npm install
2Increase npm timeout settings

If your network is slow or unreliable, increase the timeout values in your .npmrc:

bash
# Set fetch-retry-maxtimeout to 10 minutes (600000ms)
npm config set fetch-retry-maxtimeout 600000

# Increase fetch-retries for more retry attempts
npm config set fetch-retries 5

# Increase fetch-timeout (time per request)
npm config set fetch-timeout 300000

You can also set these directly in your ~/.npmrc file:

ini
fetch-retry-maxtimeout=600000
fetch-retries=5
fetch-timeout=300000
3Check and configure proxy settings

If you're behind a corporate proxy, npm needs to be configured to use it:

bash
# Check current proxy settings
npm config get proxy
npm config get https-proxy

# Set proxy (replace with your proxy URL)
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# If your proxy requires authentication
npm config set proxy http://username:password@proxy.company.com:8080
npm config set https-proxy http://username:password@proxy.company.com:8080

If you're NOT behind a proxy but have stale proxy settings, remove them:

bash
npm config delete proxy
npm config delete https-proxy

Also check for proxy environment variables:

bash
# Check if proxy env vars are set
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $NO_PROXY
4Clear npm cache and delete package-lock.json

Cached data can sometimes cause connectivity issues:

bash
# Clear the npm cache
npm cache clean --force

# Delete package-lock.json and node_modules
rm -rf node_modules package-lock.json

# Retry installation
npm install

On Windows:

powershell
npm cache clean --force
Remove-Item -Recurse -Force node_modules, package-lock.json
npm install
5Use --no-audit flag to reduce network requests

The audit check adds extra network requests that can timeout. Skip it temporarily:

bash
npm install --no-audit

You can also disable it permanently:

bash
npm config set audit false

Similarly, reduce maxsockets to limit parallel connections (helpful on unreliable networks):

bash
npm config set maxsockets 3
6Test connectivity to npm registry

Verify that you can reach the npm registry:

bash
# Test DNS resolution
nslookup registry.npmjs.org

# Test HTTPS connectivity
curl -I https://registry.npmjs.org

# On Windows without curl
Invoke-WebRequest -Uri https://registry.npmjs.org -Method Head

If DNS fails, try using a different DNS server (e.g., Google's 8.8.8.8 or Cloudflare's 1.1.1.1).

If HTTPS fails but HTTP works, you may have a firewall or proxy blocking HTTPS traffic.

7Switch to a different registry or mirror

If the main npm registry is slow or unreachable from your location, try a mirror:

bash
# Use the npm mirror (for China/Asia)
npm config set registry https://registry.npmmirror.com

# Or use Yarn's mirror
npm config set registry https://registry.yarnpkg.com

To reset back to the official registry:

bash
npm config set registry https://registry.npmjs.org/
8Disable VPN or adjust network settings

VPNs can cause routing issues. Try temporarily disconnecting:

1. Disconnect from your VPN
2. Run npm install again
3. If it works, you may need to configure VPN split tunneling to exclude npm traffic

On macOS, also check if you have multiple network interfaces:

bash
# List network services
networksetup -listallnetworkservices

Disable unused network interfaces that might be causing routing conflicts.

Advanced notes

### WSL2 and Docker Networking

In WSL2 or Docker, network issues are common:

WSL2:

bash
# Reset WSL network
wsl --shutdown
# Then restart WSL

If issues persist, check Windows firewall rules aren't blocking WSL network traffic.

Docker:

dockerfile
# Add to your npm install command in Dockerfile
RUN npm install --no-audit --prefer-offline --maxsockets=3

Or use a multi-stage build to cache dependencies:

dockerfile
FROM node:20 AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --no-audit

### CI/CD Retry Logic

For automated environments, add retry logic:

GitHub Actions:

yaml
- name: Install dependencies
  run: npm ci --no-audit
  env:
    NODE_OPTIONS: "--dns-result-order=ipv4first"
  timeout-minutes: 10

GitLab CI:

yaml
install:
  script:
    - npm ci --no-audit || npm ci --no-audit
  variables:
    NODE_OPTIONS: "--dns-result-order=ipv4first"

### Diagnosing with Verbose Logging

Enable verbose logging to see exactly where the timeout occurs:

bash
npm install --loglevel verbose

Or check npm debug logs:

bash
# Find the most recent debug log
ls -la ~/.npm/_logs/

# View the log
cat ~/.npm/_logs/*-debug.log

### Corporate Firewall Rules

If you're behind a corporate firewall, ensure these domains are allowed:
- registry.npmjs.org (port 443)
- npmjs.org (port 443)
- npmjs.com (port 443)

Some firewalls block large downloads - npm packages can be several MB. Ask IT to whitelist npm traffic.

### IPv6 Deep Dive

Node.js 17+ changed the default DNS resolution order to prefer IPv6. This causes issues because:
1. Your router advertises IPv6 via SLAAC
2. Node.js tries to connect via IPv6 first
3. Your ISP doesn't actually route IPv6 properly
4. Connection hangs until timeout

The permanent fix is either:
- Disable IPv6 on your router/system
- Use --dns-result-order=ipv4first flag
- Configure npm with prefer-ip-version 4

To check if IPv6 is the culprit:

bash
# Try forcing IPv4 at the curl level
curl -4 https://registry.npmjs.org

# vs IPv6
curl -6 https://registry.npmjs.org

If IPv4 works but IPv6 hangs, you've found your problem.

Frequently asked questions

What does "ETIMEDOUT" mean?
The ETIMEDOUT error in npm indicates that a network request to the npm registry (or a private registry) failed because it took too long to complete. By default, npm waits 30 seconds for a response before timing out. When you run npm install, npm connects to the registry to fetch package metadata and tarballs.
How do I fix "ETIMEDOUT"?
This error occurs when npm cannot establish a connection to the registry within the timeout period (default 30 seconds). Common causes include IPv6 connectivity issues, proxy misconfiguration, firewall restrictions, or slow network conditions.
What causes "ETIMEDOUT"?
IPv6 connectivity issues (most common in Node.js 18+ where IPv6 is preferred) Corporate proxy misconfiguration or missing proxy settings in npm Firewall blocking outbound connections to registry.npmjs.org on port 443
Is the "ETIMEDOUT" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading