How to Set Up a Proxy for npm: npm config, .npmrc, pnpm and Yarn

What a proxy changes and what it does not

A proxy changes only the network path between your computer and the package registry. It does not change which registry npm downloads from: that is the separate registry setting, so a proxy and a registry mirror are two different things and one does not replace the other. This guide covers npm, with short sections for pnpm and Yarn. For proxies inside the code of a Node.js program, see the Node.js guide.

• Node.js proxy guide

The three npm settings that matter

The npm config page lists three keys. proxy is the proxy for outgoing http requests (type: null, false or a URL, default null). https-proxy is the proxy for outgoing https requests (a URL, default null); the registry address https://registry.npmjs.org is an https address, so this is the key that normally matters. noproxy holds domain extensions that should skip the proxy, and its default is the value of the NO_PROXY environment variable. The page also says that the HTTP_PROXY, HTTPS_PROXY and lower-case variables are honored by the libraries npm uses underneath.

• Sources:
• npm Docs: config (proxy, https-proxy, noproxy)

Set the proxy with npm config

npm config set writes a key to your user config file unless you pass --location. npm config get prints the value back, so you can see what is stored, and npm config delete removes keys from all config files. Set both keys to the same HTTP address; the values are URLs, with the username and password in front of the host.

• Sources:
• npm Docs: config (proxy, https-proxy, noproxy)
• npm Docs: npm config

Set the proxy with npm config: example

npm config set proxy http://USERNAME:PASSWORD@HOST:PORT
npm config set https-proxy http://USERNAME:PASSWORD@HOST:PORT
npm config get https-proxy

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

Username and password

If the username or password contains characters such as @, :, / or %, write them in percent-encoded form: @ becomes %40, : becomes %3A, / becomes %2F and % becomes %25. The pnpm page asks for exactly this when a proxy URL has a username and password, and it keeps the colon between the two unencoded. The npm pages do not describe this rule, so after setting the values run npm ping (see the check below). Copying the values from My assets is safer than typing them. Keep in mind that the config file is plain text: anyone who can read ~/.npmrc can read the password.

• Sources:
• pnpm Docs: network settings

The .npmrc file and which one wins

The same settings can be typed straight into a .npmrc file. The npmrc page lists four: the per-project file in the project root (used only for that project), the per-user file ~/.npmrc, the global file $PREFIX/etc/npmrc, and a built-in file inside npm that you cannot change. They are resolved in priority order, and its example is that a setting in the user file overrides the same setting in the global file. The page also says a project file is not read in global mode. A file value can contain ${NAME}, which npm replaces with the environment variable of that name, so a password does not have to be written into the file.

• Sources:
• npm Docs: npmrc

A project .npmrc: example

# .npmrc in the project folder
proxy=http://USERNAME:PASSWORD@HOST:PORT
https-proxy=http://USERNAME:PASSWORD@HOST:PORT
noproxy=localhost,127.0.0.1

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

Environment variables

The npm config page names HTTP_PROXY, HTTPS_PROXY and NO_PROXY (and their lower-case forms) as variables the underlying libraries honor, and the pnpm page says it falls back to them too. They are handy for one terminal session: nothing is written to disk, and the setting ends when you close the window. Windows PowerShell uses $env:NAME = "value" instead of export.

• Sources:
• npm Docs: config (proxy, https-proxy, noproxy)
• pnpm Docs: network settings

Environment variables for one session: example

export HTTPS_PROXY=http://USERNAME:PASSWORD@HOST:PORT
export HTTP_PROXY=http://USERNAME:PASSWORD@HOST:PORT
export NO_PROXY=localhost,127.0.0.1
npm ping

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

Addresses that should not use the proxy

Put internal or local hosts into noproxy (npm: domain extensions, and a comma-separated string is accepted) or NO_PROXY, so that npm reaches them directly. pnpm calls the same thing noProxy: a comma-separated string of domain extensions that a proxy should not be used for. The npm page does not explain how a host name is matched against an entry, so use the full domain you need and test it.

• Sources:
• npm Docs: config (proxy, https-proxy, noproxy)
• pnpm Docs: network settings

SOCKS5

The npm config page never mentions SOCKS, and neither do the pnpm and Yarn pages we read, so this guide gives only HTTP proxy addresses. Use an HTTP proxy for these tools: choose HTTP when you generate the Proxy302 proxy.

• SOCKS5 proxies page

• Sources:
• npm Docs: config (proxy, https-proxy, noproxy)
• pnpm Docs: network settings
• Yarn Docs: .yarnrc.yml

pnpm and Yarn

pnpm: its settings are httpsProxy and httpProxy (type url, default null) and noProxy (a comma-separated string). The pnpm page says that if httpsProxy is not set it checks the HTTPS_PROXY or https_proxy environment variable, so the environment variables above also work for pnpm. Its settings page adds that proxy settings can be read from .npmrc. Yarn (modern, Berry): the .yarnrc.yml page lists httpProxy ("Proxy to use when making an HTTP request") and httpsProxy ("Define a proxy to use when making an HTTPS request"), with http:// examples. We did not find a noProxy setting on that page.

• Sources:
• pnpm Docs: network settings
• pnpm Docs: settings
• Yarn Docs: .yarnrc.yml

Yarn Berry: .yarnrc.yml: example

httpProxy: "http://USERNAME:PASSWORD@HOST:PORT"
httpsProxy: "http://USERNAME:PASSWORD@HOST:PORT"

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

How to switch the proxy off

npm config delete removes the keys from all config files. Then run npm config list: it prints all settings, and npm config list -l adds the defaults. If a proxy still shows up, look at the environment variables and unset HTTP_PROXY, HTTPS_PROXY and NO_PROXY in that terminal, and check the project .npmrc as well.

• Sources:
• npm Docs: npm config
• npm Docs: npmrc

Switch the proxy off: example

npm config delete proxy https-proxy noproxy
npm config list

There is nothing to replace here. Run the two commands as they are: the first removes the three settings, the second lists what is left.

How to check that npm uses the proxy

1. Print what is set

   Run npm config get proxy and npm config get https-proxy. They echo the stored value.

2. Ping the registry

   npm ping contacts the configured registry and verifies authentication. A working path prints a PING line and a PONG line with the time in milliseconds; a failure prints an error instead.

3. Check the exit address with curl

   The second command below shows the IP, country and network that websites see through the same proxy.

   • how to check your proxy's IP, country and ISP

4. Then install something small

   In an empty folder run npm init -y and npm install is-odd. If it installs, you are done.

How to check that npm uses the proxy: example

npm ping
curl -x http://USERNAME:PASSWORD@HOST:PORT https://ipinfo.io/json

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets.

Common errors

• 407 Proxy Authentication Required. The proxy rejected the username or password. Copy them again and check the percent-encoding.

• npm ping fails or times out. Wrong HOST or PORT, or the lease has ended. Test the same address with the curl command above.

• Packages still come directly. Run npm config list and check for a project .npmrc or environment variable that overrides the setting.

• A package from your company's own registry fails. Add its domain to noproxy so npm reaches it directly.

• authentication required guide
• connection failed guide

How to do it with Proxy302

Every command here needs only the host, port, username and password of a Proxy302 proxy. npm, pnpm and Yarn take an HTTP address, so choose HTTP when you generate the proxy. Rotating residential traffic is billed per GB and the exit country is set when you generate the proxy; HTTP is on port 2222 and SOCKS5 on port 3333 of proxy.proxy302.com. A static ISP IP stays fixed for the whole lease and does not rotate, which suits a tool that you want to always leave from the same address. HTTP or SOCKS5 is chosen when you buy, and one IP carries one protocol.

• rotating residential page
• SOCKS5 proxies page

• Sources:
• Proxy302 product facts and price list

How to do it with Proxy302: steps

1. Step 1

   Open the rotating residential page, choose the line, keep Protocol on HTTP, then click Review cost and generate.

2. Step 2

   Open My assets (the console page that holds everything you bought) and copy HOST, PORT, USERNAME and PASSWORD. The Connect page shows a ready example with your own endpoint.

3. Step 3

   Put the values into the commands above.

4. Step 4

   Confirm the exit with https://ipinfo.io/json through the proxy.

   • how to check your proxy's IP, country and ISP

5. Step 5

   From mainland China, start the helper tool from the Connect page first and keep it open while you use the proxy.

   • Helper tool guide

Prices and limits

The Budget line costs US$1.50 per GB, US$1.35 per GB in a 100 GB package and US$1.20 per GB at 300 GB. A static ISP IP costs US$0.50 for one day and US$7.99 for 30 days. There is no free trial, and the smallest purchase is 1 GB or one IP for one day. Which exit locations are available changes daily.

• Sources:
• Proxy302 product facts and price list

FAQ

Read next

Node.js proxy setup

Ways to use an HTTP or SOCKS5 proxy in Node.js, with short examples and an exit check.

pip proxy setup

Set a proxy for pip with --proxy, pip config or environment variables, learn which setting wins, switch it off and check it.

407 Proxy Authentication Required

HTTP 407 Proxy Authentication Required comes from the proxy server, not from the website you are trying to reach.

Fix ERR_PROXY_CONNECTION_FAILED

The ERR_PROXY_CONNECTION_FAILED error appears in Chrome and Edge when the browser cannot establish a connection with a proxy server.