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.
# --- 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.
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
- npm and yarn behind a proxy
- curl with a SOCKS5 proxy
- how to check npm and yarn behind a proxy
- npm and yarn behind a proxy for scraping
- npm and yarn behind a proxy settings
- SOCKS5 authentication methods (RFC 1929)
- vpn kill switch tutorial
- http proxy with crypto payment
- how to configure wireguard
- openvpn
- wireguard
- VPN and proxy FAQ
Real search phrases this page answers — the linked ones open the page that covers them in depth.