Node.js Guide · 1 min read

npm and yarn behind a proxy

Corporate networks break npm install in predictable ways. Here is how to configure npm and both major yarn versions to install through an HTTP proxy — plus the environment variables the whole Node toolchain shares.

npm, yarn and the HTTP proxy

Package managers download over HTTPS, so they need an HTTP CONNECT proxy — which is exactly the s4m HTTP endpoint on port 3128. npm keeps its own config, so setting the shell's environment variables is not always enough; you usually set both proxy and https-proxy in npm config so registry traffic is routed. Yarn's two generations differ: classic yarn v1 reads its own proxy / https-proxy settings (and largely honours npm's), while Yarn Berry (v2+) uses httpProxy and httpsProxy keys in .yarnrc.yml.

Across all of them, the standard http_proxy, https_proxy and no_proxy environment variables are honoured too, which is the fastest way to fix a one-off npm install on a locked-down machine. With s4m you authenticate with USER:PASS against proxy.s4m.online:3128. See the proxy page and the shared environment-variable guide; the sibling pip and conda guide covers the Python equivalent.

Configure npm, yarn v1 and Berry

Persistent config for each tool plus the environment-variable fallback. Replace USER:PASS before running.

bash
# --- npm: persistent config (writes to ~/.npmrc) ---
npm config set proxy       http://USER:[email protected]:3128
npm config set https-proxy http://USER:[email protected]:3128
npm config set noproxy     localhost,127.0.0.1,.internal
npm install
# To undo later:
# npm config delete proxy && npm config delete https-proxy

# --- yarn v1 (classic) ---
yarn config set proxy       http://USER:[email protected]:3128
yarn config set https-proxy http://USER:[email protected]:3128

# --- Yarn Berry (v2+): .yarnrc.yml ---
cat >> .yarnrc.yml <<'YML'
httpProxy: "http://USER:[email protected]:3128"
httpsProxy: "http://USER:[email protected]:3128"
YML

# --- Environment variables: quickest one-off fix ---
export https_proxy="http://USER:[email protected]:3128"
export http_proxy="http://USER:[email protected]:3128"
export no_proxy="localhost,127.0.0.1,.internal"
npm install

Fix npm install behind a proxy

The order to try things when installs are timing out.

Confirm it is the proxy

Run npm install -ddd (or with --verbose) and look for ETIMEDOUT or ECONNREFUSED to the registry — that points at a blocked outbound connection needing a proxy.

Set npm proxy and https-proxy

Use npm config set for both proxy and https-proxy pointing at http://USER:[email protected]:3128. Registry traffic is HTTPS, so https-proxy is the one that usually matters.

Match your yarn version

For yarn v1 use yarn config set; for Yarn Berry add httpProxy and httpsProxy to .yarnrc.yml. Do not mix the two config styles.

Add noproxy for internal registries

If you also use a private registry on the LAN, add its host to noproxy / no_proxy so it is reached directly instead of through the external proxy.

Auth, private registries and gotchas

Two things break installs even after the proxy is set. First, special characters in the password: if it contains @, : or #, URL-encode them (for example @ becomes %40) or the config parses the URL wrong. Second, a mix of public and private registries: put any internal registry host in noproxy so it is reached directly, while the public npm registry goes through the proxy.

s4m's HTTP endpoint is an authenticated datacenter proxy, metered pay-as-you-go — a clean fit for CI runners and developer machines that must reach npm from behind a controlled egress. It is not a residential proxy and it is not a package cache; for offline installs use a real registry mirror. When your CI needs a single allowlisted egress IP, add a dedicated personal IP. A 407 means bad credentials — see the 407 guide. The same endpoint powers pip/conda and Docker; validate it with the tools.

FAQ

Questions, answered

Why does npm install hang or time out behind a proxy?

The registry is reached over HTTPS and your outbound connection is blocked. Set npm's proxy and https-proxy (and/or the http_proxy/https_proxy env vars) to route through http://USER:[email protected]:3128.

How do I configure Yarn Berry versus yarn v1?

Yarn v1 uses yarn config set proxy / https-proxy. Yarn Berry (v2+) uses httpProxy and httpsProxy keys in .yarnrc.yml. Use one style per project; do not mix them.

My password has special characters and the proxy fails — why?

npm parses the proxy value as a URL, so characters like @, : or # in the password must be URL-encoded (for example @ becomes %40). After encoding, the credentials parse correctly.

How do I keep an internal registry off the proxy?

Add the internal registry's hostname to the noproxy (npm) or no_proxy (env) list. That host is then reached directly while public registry traffic still goes through the proxy.

Unblock your Node installs

Route npm and yarn through the authenticated HTTP endpoint on proxy.s4m.online:3128. Metered pay-as-you-go, with a dedicated IP when CI needs one allowlisted egress.

People found this page by searching for

Real search phrases this page answers — the linked ones open the page that covers them in depth.