Configuring npm, Yarn and pnpm to Install Packages Through a Proxy

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

Give CI runners one known exit IP

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_proxy and npm_config_noproxy come next.
  • Project .npmrc beside package.json, written with npm config set ... --location=project.
  • User ~/.npmrc, the default target of npm config set.
  • Global $PREFIX/etc/npmrc (see npm 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 detail

Proxy 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]:PORT

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

If 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]:PORT

Yarn 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 ci
docker 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

Related articles

Proxy setup
Running Docker containers behind an authenticated HTTP proxy
Send Docker container, build and image pull traffic through an authenticated HTTP(S) proxy, keep service-to-service calls local with NO_PROXY and verify the IP.
Proxy setup
Authenticated proxies in Node.js: Axios, native fetch and Got
Route Node.js and TypeScript requests through an authenticated HTTP(S) proxy: https-proxy-agent for Axios, undici ProxyAgent for fetch, hpagent for Got.
Free tools
Check proxies in bulk: status, exit IP and latency
Free online proxy checker: paste up to 100 ip:port:user:pass lines and see which proxies work, their exit IP and latency, plus what each failure result means.
Products
Dedicated datacenter proxies: one private IPv4 per customer
Private IPv4 proxies in the US, Vietnam, Japan, South Korea, Singapore, the UK and Hong Kong. One tenant per IP, HTTP(S) and SOCKS5, no traffic metering.
Proxy setup
Set up your proxy, tool by tool
Proxy setup instructions you can follow with the dashboard open: antidetect browsers, operating systems, browser extensions and scraping libraries, all with authenticated HTTP(S) or SOCKS5.
Knowledge base
Connecting to SSH Servers Through an Authenticated SOCKS5 Proxy
SSH through a SOCKS5 proxy with ProxyCommand and ncat, why OpenBSD nc -X 5 cannot log in, HTTP CONNECT tunnels, and how to keep the proxy password private.
Knowledge base
Setting Up proxychains-ng With an Authenticated SOCKS5 Proxy
Proxychains SOCKS5 with username and password: the ProxyList line, which proxychains4.conf is read, proxy_dns, chain types and fixing Go tools that bypass it.
Knowledge base
Routing Invoke-WebRequest and Invoke-RestMethod Through an Authenticated Proxy
Use a PowerShell Invoke-WebRequest proxy with -ProxyCredential, set a session default proxy, and handle the gaps between Windows PowerShell 5.1 and 7.
Products
Static ISP proxies: residential IPs on consumer networks
Static ISP proxies in the United States and Vietnam: fixed IPs registered to consumer internet providers, rented to one customer, with unmetered traffic.
Pricing
Proxy prices per IP, by location and volume
Current per-IP rates for private IPv4 and static ISP proxies in the US, Vietnam, Japan, South Korea, Singapore, the UK and Hong Kong, with volume discounts.