npm Proxy Settings: npm config set proxy, .npmrc and Node.js Proxy Authentication

Developer guide · Last reviewed 1 October 2026 · 14 min read

An npm proxy setting tells the npm CLI to reach the registry through a proxy server, usually because a company network allows no direct internet access. You set it with two keys, proxy and https-proxy, and add a username and password to the URL when the proxy needs a login. This guide covers the npm side step by step (npm config set, .npmrc, noproxy, encoded passwords and certificate errors), then the other half of the search: sending requests from your own Node.js code through an authenticated proxy with fetch, undici, axios and the proxy-agent packages, for example through rotating residential proxies.

What “npm Proxy” Means

People searching for an npm proxy usually want one of three things, and the answer is different for each:

• npm itself behind a proxy. npm install fails on a network that only allows traffic through a proxy server. The fix is npm configuration: the proxy, https-proxy and noproxy keys, set with npm config or in an .npmrc file.
• Your Node.js code through a proxy. A script that calls APIs or collects web data should leave from a proxy IP. npm settings have no effect here. The proxy goes into the HTTP client in your code: fetch, undici, axios or an agent from the https-proxy-agent family.
• A package called http-proxy. This is a library for building your own proxy server, such as a reverse proxy or load balancer. It doesn’t send your requests through someone else’s proxy. It gets its own section below, because many searches that land here are really looking for it.

A fourth meaning comes up in company setups: a registry proxy, such as Verdaccio, which its documentation calls a lightweight private npm proxy registry. That is a mirror of the npm registry that caches packages. You point npm at it with the registry key, not the proxy key.

How to Set an npm Proxy with npm config

npm’s configuration reference defines proxy as the proxy for outgoing HTTP requests and https-proxy as the proxy for outgoing HTTPS requests. Both default to null, which means no proxy. The public registry is served over HTTPS, so https-proxy is the one that matters most, but setting both avoids surprises. In npm’s own request code, https-proxy is used when it is set and proxy is the fallback.

# set both keys (written to your user config file, ~/.npmrc)
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

# check what npm will use
npm config get https-proxy
npm config list

# test the connection to the registry
npm ping
npm view npm version

Three details catch people out:

• The https-proxy URL usually starts with http://. The scheme describes how npm talks to the proxy, not to the registry. Most proxies accept a plain HTTP connection and then open an HTTPS tunnel with the CONNECT method, defined in RFC 9110. Use https:// only if the proxy itself expects TLS on its port.
• Include the scheme. A value like proxy.example.com:8080 without http:// isn’t a valid proxy URL. npm’s network library rejects unsupported proxy protocols with an EINVALIDPROXY error.
• npm config set writes to your user file. The npm config docs say it modifies the user configuration file unless you pass --location. Add --location project to write the setting to the project’s .npmrc instead, or --location global for every user on the machine.

To remove the npm proxy again, for example when you take a laptop home, run npm config delete proxy and npm config delete https-proxy. The same commands work on Windows, macOS and Linux.

npm Proxy Authentication: Username, Password and Special Characters

When a proxy needs a login, npm has no separate username or password setting for it. The credentials go into the proxy URL, in the userinfo part before the host, as defined in RFC 3986: http://USER:PASS@host:port. If they are missing or wrong, the proxy answers with status 407, Proxy Authentication Required, which RFC 9110 defines for exactly this case.

npm config set proxy http://USERNAME:PASSWORD@v2.proxyempire.io:5000
npm config set https-proxy http://USERNAME:PASSWORD@v2.proxyempire.io:5000

The part that breaks most setups is the password. Characters that have a meaning in a URL, such as @, :, /, #, ? and %, must be percent-encoded, or the URL is read wrongly and the proxy receives the wrong credentials. A password of p@ss:word#1 becomes p%40ss%3Aword%231. You can produce the encoded form with JavaScript’s encodeURIComponent():

node -e "console.log(encodeURIComponent(process.argv[1]))" "p@ss:word#1"
# p%40ss%3Aword%231

Don’t wrap the credentials in quotes inside the URL. The older version of this guide showed http://"user:pass"@host; the quotes become part of the username and the login fails. If the value contains characters your shell treats specially, quote the whole URL on the command line instead, as the environment-variable examples below do.

.npmrc, Environment Variables and noproxy

npm reads its settings from four .npmrc files: the project file next to package.json, the user file ~/.npmrc, the global file $PREFIX/etc/npmrc and npm’s built-in file. They use a simple key = value format, and the npmrc docs say environment variables can be inserted with ${VARIABLE_NAME}. That lets a project file carry the proxy settings while the password stays in the environment:

proxy=http://${PROXY_USER}:${PROXY_PASS}@v2.proxyempire.io:5000
https-proxy=http://${PROXY_USER}:${PROXY_PASS}@v2.proxyempire.io:5000
noproxy=localhost,127.0.0.1,.internal.example.com

If the password contains special characters, store the encoded form in PROXY_PASS, because the value is placed into the URL as it is.

You can also skip the files. npm honours the standard HTTPS_PROXY, HTTP_PROXY and NO_PROXY variables, and any variable that starts with npm_config_ sets the matching npm key, with underscores in place of dashes. That is the usual way to configure an npm proxy in CI:

# macOS / Linux
export npm_config_https_proxy="http://USERNAME:PASSWORD@v2.proxyempire.io:5000"
export npm_config_proxy="$npm_config_https_proxy"

# Windows PowerShell
$env:npm_config_https_proxy = "http://USERNAME:PASSWORD@v2.proxyempire.io:5000"
$env:npm_config_proxy = $env:npm_config_https_proxy

# Windows cmd.exe
set npm_config_https_proxy=http://USERNAME:PASSWORD@v2.proxyempire.io:5000
set npm_config_proxy=%npm_config_https_proxy%

Bypass the proxy for internal hosts with noproxy

The noproxy key lists domain extensions that should bypass the proxy, as a comma-separated string. It defaults to the value of the NO_PROXY environment variable. Add your private registry, internal Git server and localhost here, so traffic that should stay inside the network never goes to the proxy. npm matches these entries by domain suffix, so .internal.example.com covers every host under that domain.

This matters with a commercial proxy too. ProxyEmpire’s gateway carries web traffic on ports 80 and 443 by default, so a private registry on another port, or a host that only exists on your company network, belongs in noproxy.

strict-ssl, cafile and Certificate Errors

Some company proxies inspect HTTPS traffic. They end the TLS connection themselves and present their own certificate, signed by a company certificate authority. npm doesn’t trust that authority by default, so installs fail with certificate errors such as SELF_SIGNED_CERT_IN_CHAIN.

The common advice is npm config set strict-ssl false. npm’s docs describe strict-ssl as whether to validate SSL keys when talking to the registry over HTTPS, and it defaults to true. Turning it off removes the check that protects you from a tampered package download, so treat it as a short test, not a fix. The proper fix is to trust the company’s certificate:

# typical errors: SELF_SIGNED_CERT_IN_CHAIN, UNABLE_TO_GET_ISSUER_CERT_LOCALLY

# npm: add the CA file (PEM format, one or more certificates)
npm config set cafile /path/to/company-ca.pem

# Node.js scripts and install scripts: extend the trusted roots
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

Node.js documents NODE_EXTRA_CA_CERTS as a way to extend the well-known root certificates with extra ones from a PEM file, which helps when package install scripts download files themselves. A tunnelling proxy that uses CONNECT, like ProxyEmpire’s gateway, doesn’t cause these errors: the TLS handshake happens between npm and the registry, and the proxy only passes encrypted bytes along.

The http-proxy Package on npm: Building a Proxy, Not Using One

The http-proxy package, also known as node-http-proxy, is not a way to send requests through a proxy. Its README describes it as a programmable HTTP proxying library with WebSocket support, suitable for reverse proxies and load balancers. You use it to run a proxy: your Node.js server receives requests and forwards them to a target server.

const httpProxy = require('http-proxy');

// requests to http://localhost:8000 are forwarded to the app on port 9000
httpProxy.createProxyServer({ target: 'http://localhost:9000' }).listen(8000);

The package still has millions of weekly downloads, but its latest release, 1.18.1, dates from May 2020. For Express, Connect or Next.js apps, http-proxy-middleware wraps the same idea as middleware. If what you actually want is for your requests to leave through a proxy IP, you need a client-side package instead:

Node.js fetch Through an Authenticated Proxy

Node.js’s global fetch() ignores npm’s settings and, by default, the HTTPS_PROXY variable too. There are two documented ways to proxy it.

Option 1: built-in proxy support (Node.js 24.5+ and 22.21+)

Recent Node.js releases can read the proxy from the environment. The Node.js HTTP docs explain that when NODE_USE_ENV_PROXY=1 is set, or Node is started with --use-env-proxy, requests through the default agent follow HTTP_PROXY, HTTPS_PROXY and NO_PROXY. The docs show credentials in the proxy URL and show fetch() being proxied the same way. The feature is marked as active development, so check the docs for your exact version.

# macOS / Linux
export HTTPS_PROXY="http://USERNAME:PASSWORD@v2.proxyempire.io:5000"
export NO_PROXY="localhost,127.0.0.1"
node --use-env-proxy app.mjs

# app.mjs
const res = await fetch('https://api.ipify.org?format=json');
console.log(await res.json());   // shows the proxy's IP, not yours

For a single client instead of the whole process, http.Agent and https.Agent accept a proxyEnv option on the same Node versions, for example new https.Agent({ proxyEnv: { HTTPS_PROXY: proxyUrl } }).

Option 2: undici ProxyAgent (any supported Node version)

Node’s fetch is built on undici. Install the undici package and pass a ProxyAgent as the dispatcher. undici’s docs say HTTPS targets go through a CONNECT tunnel, and the token option sets the Proxy-Authorization header sent to the proxy:

// npm install undici
import { fetch, ProxyAgent } from 'undici';

const dispatcher = new ProxyAgent({
  uri: 'http://v2.proxyempire.io:5000',
  token: 'Basic ' + Buffer.from(
    `${process.env.PROXY_USER}:${process.env.PROXY_PASS}`
  ).toString('base64'),
});

const res = await fetch('https://api.ipify.org?format=json', { dispatcher });
console.log(await res.json());

Import fetch from undici as shown, rather than mixing the installed package’s ProxyAgent with the global fetch. undici’s README notes that the global fetch is limited to the undici version bundled with your Node.js release, which may not match the one you installed. To proxy every undici request in the process, pass the agent to setGlobalDispatcher(). The examples use top-level await, so save them as .mjs files or set "type": "module" in package.json.

axios with an Authenticated Proxy

axios has a proxy request option for Node.js with protocol, host, port and an auth object for the username and password. It also reads http_proxy, https_proxy and no_proxy from the environment, and proxy: false turns proxying off.

import axios from 'axios';

const res = await axios.get('https://api.ipify.org?format=json', {
  proxy: {
    protocol: 'http',
    host: 'v2.proxyempire.io',
    port: 5000,
    auth: {
      username: process.env.PROXY_USER,
      password: process.env.PROXY_PASS,
    },
  },
});
console.log(res.data);

axios’s README says that for https:// targets it opens a CONNECT tunnel and sends the credentials only on that request. Its changelog shows several proxy fixes in recent 1.x releases, so keep axios up to date. If you are stuck on an older version, or want identical behaviour across clients, give axios an agent and switch its own proxy handling off:

import axios from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';

const user = encodeURIComponent(process.env.PROXY_USER);
const pass = encodeURIComponent(process.env.PROXY_PASS);
const agent = new HttpsProxyAgent(`http://${user}:${pass}@v2.proxyempire.io:5000`);

const res = await axios.get('https://api.ipify.org?format=json', {
  httpsAgent: agent,
  proxy: false,   // let the agent handle the proxy
});
console.log(res.data);

https-proxy-agent, socks-proxy-agent and the https Module

The https-proxy-agent, http-proxy-agent and socks-proxy-agent packages come from the same proxy-agents project. Each one is an http.Agent, so it works with Node’s https module and with any library that accepts an agent option, including the ws WebSocket client. https-proxy-agent reads the username and password from the proxy URL, decodes them and sends them as a Basic Proxy-Authorization header on the CONNECT request.

import https from 'node:https';
import { HttpsProxyAgent } from 'https-proxy-agent';

const user = encodeURIComponent(process.env.PROXY_USER);
const pass = encodeURIComponent(process.env.PROXY_PASS);
const agent = new HttpsProxyAgent(`http://${user}:${pass}@v2.proxyempire.io:5000`);

https.get('https://api.ipify.org', { agent }, (res) => {
  res.pipe(process.stdout);
});

For SOCKS5, swap in socks-proxy-agent. ProxyEmpire accepts SOCKS5 on the same host, port and credentials. Use the socks5h:// scheme if the proxy should resolve host names: the package’s source shows that socks5:// looks the name up locally first, while socks5h:// sends it to the proxy.

import https from 'node:https';
import { SocksProxyAgent } from 'socks-proxy-agent';

const user = encodeURIComponent(process.env.PROXY_USER);
const pass = encodeURIComponent(process.env.PROXY_PASS);
const agent = new SocksProxyAgent(`socks5h://${user}:${pass}@v2.proxyempire.io:5000`);

https.get('https://api.ipify.org', { agent }, (res) => res.pipe(process.stdout));

No dependencies: a CONNECT tunnel with core modules

You can also do it with Node’s core modules alone, which is what the old version of this guide attempted. Send a CONNECT request with a Proxy-Authorization header, wait for the connect event, then run TLS over the returned socket. It is useful for understanding what the libraries do, though an agent is easier to maintain.

const http = require('node:http');
const https = require('node:https');
const tls = require('node:tls');

const target = 'api.ipify.org';
const auth = 'Basic ' + Buffer.from(
  `${process.env.PROXY_USER}:${process.env.PROXY_PASS}`
).toString('base64');

const req = http.request({
  host: 'v2.proxyempire.io',
  port: 5000,
  method: 'CONNECT',
  path: `${target}:443`,
  headers: { Host: `${target}:443`, 'Proxy-Authorization': auth },
});

req.on('connect', (res, socket) => {
  if (res.statusCode !== 200) {
    console.error('Proxy refused the tunnel:', res.statusCode);  // 407 = check credentials
    socket.destroy();
    return;
  }
  https.get({
    host: target,
    path: '/',
    createConnection: () => tls.connect({ socket, servername: target }),
  }, (r) => r.pipe(process.stdout));
});

req.on('error', (err) => console.error(err));
req.end();

For headless Chrome, the proxy goes into the browser launch options instead of an agent; our Puppeteer proxy guide covers that setup with authentication.

Rotating and Sticky IPs from Node.js

A proxy in your npm configuration is usually a fixed company gateway. A proxy in your Node.js code is often chosen for its exit IP: a residential or mobile address in a particular country, a new IP for each request, or one IP kept for a whole login flow. With ProxyEmpire, those choices are part of the proxy username you generate in the dashboard, so the host and port in your code stay the same.

Create agents once and reuse them. undici’s ProxyAgent and the proxy-agents packages keep connections open to the proxy, so building a new agent for every request throws that away. When you change targeting in the dashboard, the username changes too; update the value your application reads, or you’ll get 407 errors. The same gateway serves rotating mobile proxies on 4G and 5G carrier networks, and SOCKS or HTTP works with either.

Troubleshooting npm Proxy and Node.js Proxy Errors

To separate credential problems from Node.js problems, test the same proxy details with curl. If curl works and Node doesn’t, the issue is in your client code.

curl -x http://v2.proxyempire.io:5000 -U "USERNAME:PASSWORD" https://api.ipify.org

Our curl with proxy guide explains the flags, and the 407 Proxy Authentication Required guide goes deeper into that error.

npm Proxy FAQ

References

1. npm Docs — Config: proxy, https-proxy, noproxy, strict-ssl, cafile. docs.npmjs.com/cli/v12/using-npm/config
2. npm Docs — npm config command. docs.npmjs.com/cli/v12/commands/npm-config
3. npm Docs — .npmrc files and environment variables. docs.npmjs.com/cli/v12/configuring-npm/npmrc
4. npm — @npmcli/agent, the proxy handling behind the npm CLI. github.com/npm/agent
5. Node.js — HTTP, Built-in Proxy Support. nodejs.org/api/http.html
6. Node.js — Command-line options: –use-env-proxy, NODE_EXTRA_CA_CERTS. nodejs.org/api/cli.html
7. undici — ProxyAgent. github.com/nodejs/undici
8. axios — Request config, proxy option. axios-http.com/docs/req_config
9. proxy-agents — https-proxy-agent, http-proxy-agent, socks-proxy-agent, proxy-agent. github.com/TooTallNate/proxy-agents
10. node-http-proxy — the http-proxy package. github.com/http-party/node-http-proxy
11. IETF — RFC 3986, URI syntax: userinfo and percent-encoding. rfc-editor.org/rfc/rfc3986
12. IETF — RFC 9110, HTTP Semantics: CONNECT and 407. rfc-editor.org/rfc/rfc9110