Configuring npm, Yarn and pnpm to Install Packages Through a Proxy
By the ProxyV4 Engineering Team · Updated:
Run npm config set proxy http://USER:PASS@IP:PORT and npm config set https-proxy http://USER:PASS@IP:PORT; npm stores both in your user .npmrc and uses them for every install. Yarn and pnpm read similar keys under different names, and CI builds need the value injected without baking credentials into images. Each package manager is covered below, along with the errors that tell you something is still wrong.
What proxy and https-proxy each control
npm has two keys because it picks the proxy by the scheme of the URL it is fetching. proxy is used for http:// registry URLs and https-proxy for https:// ones. The public registry is HTTPS, so https-proxy is the key that matters in practice; set both so a plain-HTTP mirror does not slip past the proxy.
npm config set proxy http://USER:[email protected]:PORT
npm config set https-proxy http://USER:[email protected]:PORT
npm config set noproxy "localhost,127.0.0.1,.internal.example.com"The value of https-proxy normally starts with http://. That scheme says how npm talks to the proxy, not to the registry. npm opens a CONNECT tunnel and the TLS session with the registry runs inside it, so the proxy never sees package contents or your auth token.
Special characters in the password need percent-encoding (@ becomes %40, : becomes %3A, # becomes %23), or npm will misread where the host begins.
Where npm keeps proxy settings and which one wins
npm merges configuration from several sources. Knowing the order saves time when a value refuses to change.
The .npmrc hierarchy
When none of the keys are set, npm falls back to the standard HTTPS_PROXY, HTTP_PROXY and NO_PROXY environment variables.
- Command line flags such as
--https-proxy=...win over everything. - Environment variables named
npm_config_https_proxy,npm_config_proxyandnpm_config_noproxycome next. - Project
.npmrcbesidepackage.json, written withnpm config set ... --location=project. - User
~/.npmrc, the default target ofnpm config set. - Global
$PREFIX/etc/npmrc(seenpm config get prefix), then npm's built-in defaults.
Inspecting the effective value
Check what npm will actually use, then make a request that needs the network.
npm config get https-proxy
npm config list # shows each value and the file it came from
npm ping # contacts the registry through the proxy
npm install --verbose # prints request-level detailProxy URLs that contain a password can appear in this output, so avoid pasting it into tickets or chat.
Yarn proxy settings: classic versus Berry
Yarn 1 and Yarn 2+ are different programs with different config files. Run yarn --version before following any guide.
Yarn 1 (classic)
Classic Yarn mirrors npm's key names and writes them to ~/.yarnrc. It also reads .npmrc, so an existing npm proxy often already works.
yarn config set proxy http://USER:[email protected]:PORT
yarn config set https-proxy http://USER:[email protected]:PORTYarn 2, 3 and 4 (Berry)
Berry ignores .npmrc and uses camelCase keys in .yarnrc.yml. It can also scope a proxy to particular hosts with networkSettings, so only your private registry goes through the proxy.
# .yarnrc.yml
httpProxy: "http://USER:[email protected]:PORT"
httpsProxy: "http://USER:[email protected]:PORT"
# or only for one host
networkSettings:
"registry.internal.example.com":
httpsProxy: "http://USER:[email protected]:PORT"Any Berry setting can also come from an environment variable with a YARN_ prefix, such as YARN_HTTPS_PROXY, which keeps the password out of the committed file.
pnpm proxy settings
pnpm reads the npm-style proxy, https-proxy and noproxy keys from .npmrc, which is still where its documentation says network and auth settings belong. Recent pnpm releases name these settings httpProxy, httpsProxy and noProxy, and fall back to the HTTPS_PROXY, HTTP_PROXY and NO_PROXY variables when nothing is configured.
# .npmrc in the project or your home folder
proxy=http://USER:[email protected]:PORT
https-proxy=http://USER:[email protected]:PORT
noproxy=localhost,127.0.0.1If you use Corepack to pin pnpm or Yarn, remember that Corepack itself downloads the package manager before any of these settings are read. In a locked-down network, export HTTPS_PROXY in the environment so that first download also goes through the proxy.
Using a SOCKS5 proxy with npm
Recent npm releases route requests through the @npmcli/agent package, which recognises SOCKS URLs. You can put socks5:// or socks5h:// in proxy and https-proxy; the h variant asks the proxy to resolve registry hostnames, which helps when local DNS is filtered.
npm config set https-proxy socks5h://USER:[email protected]:PORTYarn and pnpm do not document SOCKS support for their proxy keys, so keep them on the proxy's HTTP mode. A proxy that serves HTTP and SOCKS5 on the same port lets every tool use the same address with a different scheme. If you are deciding between the two, the HTTP vs SOCKS5 guide lays out the trade-offs.
When CI needs a known exit IP
Hosted runners pick up a different public address on almost every job. That becomes a problem when a private registry, an artifact server or a license check during postinstall only accepts connections from approved addresses. Routing installs through a proxy with a fixed IP gives the other side exactly one address to trust.
ProxyV4 private datacenter IPv4 proxies fit this: one tenant per IP for the whole term, the same address while active, and the same IP again when you renew before expiry. Each one supports HTTP(S) and SOCKS5 with username and password login, so it works with npm, Yarn and pnpm alike. Traffic is not metered, so cold caches and large node_modules trees do not change the bill.
If your jobs only pull from the public npm registry, you do not need any of this. You can order a single IP, run one pipeline through it, then compare live per-IP prices on the pricing page before adding runners.
Proxy settings for CI runners and Docker builds
The hard part in CI is getting the proxy URL into the job without leaking the password into logs, caches or image layers. Two patterns work well.
In a pipeline, expose the URL as a secret and map it to npm's environment variable for the install step only:
# GitHub Actions step
- run: npm ci
env:
npm_config_https_proxy: ${{ secrets.NPM_HTTPS_PROXY }}
npm_config_proxy: ${{ secrets.NPM_HTTPS_PROXY }}In a Dockerfile, mount an .npmrc that holds the proxy as a BuildKit secret. It is available during npm ci and is not written into any layer.
# syntax=docker/dockerfile:1
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm cidocker build --secret id=npmrc,src=$HOME/.npmrc-ci -t app .For the daemon-level and container-level variables Docker reads, see the Docker proxy setup guide; the secret mount above is specific to package installs.
Troubleshooting npm proxy errors
To remove the proxy completely, run npm config delete proxy and npm config delete https-proxy, and do the same in any project .npmrc.
ECONNREFUSED, ETIMEDOUT or ECONNRESET
npm cannot reach the proxy, or the proxy dropped the tunnel. Confirm host and port, and that the scheme matches the port's mode; an http:// URL against a SOCKS-only port fails this way. Test the line on its own with the proxy checker before changing npm settings again.
407 in the verbose log
The proxy rejected the credentials. Re-encode the password, then look for an npm_config_* or HTTPS_PROXY variable that overrides the .npmrc you just edited.
SELF_SIGNED_CERT_IN_CHAIN or UNABLE_TO_GET_ISSUER_CERT_LOCALLY
A corporate proxy is inspecting TLS. Give npm the company CA with npm config set cafile /path/to/corp-ca.pem (or NODE_EXTRA_CA_CERTS for Node as a whole) instead of setting strict-ssl false, which turns off certificate checks for every package.
Frequently asked questions
Should https-proxy start with http:// or https://?
Usually http://. The scheme describes the connection to the proxy itself; HTTPS traffic to the registry is tunnelled through it and stays encrypted.
Does npm use the HTTPS_PROXY environment variable?
Yes, when https-proxy is not set in any config. A value in .npmrc or an npm_config_https_proxy variable takes priority.
Why does Yarn ignore my npm proxy settings?
Yarn 2 and later do not read .npmrc. Set httpProxy and httpsProxy in .yarnrc.yml or use YARN_HTTPS_PROXY.
How do I turn the npm proxy off for one internal registry?
Add the host or domain suffix to noproxy, for example .internal.example.com, or set NO_PROXY in the environment.
Can one proxy serve npm over HTTP and another tool over SOCKS5?
With ProxyV4 you choose HTTP only, SOCKS5 only or both on one port per order. Switching modes can move the proxy to a new port, so copy the line again afterwards.
Give CI runners one known exit IP
Route installs through a private IPv4 with HTTP(S) and SOCKS5, username and password login and unmetered traffic. Order one IP, test a pipeline, then scale.
Get a static IP