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

npmBEGINNERMEDIUM

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 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.

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:[email protected]:8080
npm config set https-proxy http://username:[email protected]: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.

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

What this error means

Typical symptoms

Common causes

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

Advanced notes

Related errors

Official resources & further reading