Node.js Reference ยท CLI Flags
Node.js NODE_USE_ENV_PROXY environment variable
Reference for NODE_USE_ENV_PROXY: make the http and https modules honor HTTP_PROXY, HTTPS_PROXY and NO_PROXY, with a runnable loopback proxy demo.
Behind a corporate network, outgoing web requests often have to go through a proxy server. Many tools read the conventional environment variables HTTP_PROXY, HTTPS_PROXY and NO_PROXY for this. Node.js does not do so by default: http.request(), https.request() and fetch() connect directly, no matter what those variables say.
Setting NODE_USE_ENV_PROXY=1 switches the behavior on for the whole process. Requests then go to the proxy named by the variable that matches their protocol, unless the target host is excluded by NO_PROXY.
// shell: NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://proxy.internal:3128 node app.js
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
// NODE_USE_ENV_PROXY=1 // HTTP_PROXY=http://host:port (for http: URLs) // HTTPS_PROXY=http://host:port (for https: URLs) // NO_PROXY=host1,.domain.com,10.0.0.0/8 (hosts that bypass the proxy)
| Variable | Description |
|---|---|
NODE_USE_ENV_PROXY |
Set to 1 to enable the feature. Without it the other variables are ignored. |
HTTP_PROXY |
Proxy URL for plain http: requests. Lowercase http_proxy is read as well. |
HTTPS_PROXY |
Proxy URL for https: requests, which are tunneled with CONNECT. |
NO_PROXY |
Comma-separated list of hosts or domains that connect directly. * means everything. |
Usage notes
- Opt-in. Node has no proxy variables behavior until you set
NODE_USE_ENV_PROXY=1. Libraries such asaxiosorgotmay read the variables on their own, so the same shell can behave differently for different clients. - Loopback is proxied too unless you list it in
NO_PROXY. When a proxy appears to swallow requests tolocalhost, addlocalhost,127.0.0.1to the list. - HTTPS through a proxy makes the proxy open a TCP tunnel with
CONNECT; TLS still runs end to end, so certificate checks still use the normal trust store (seeNODE_EXTRA_CA_CERTSif the proxy inspects TLS). - Read at startup. Set the variables in the environment of the process rather than assigning
process.envlater. - Applies to
httpandhttpsrequests that use the default agent. A customagentyou pass in is in charge of its own connections. Whetherfetch()follows the variables depends on the Node release; the demos here usehttp, so testfetch()on your version or give undici anEnvHttpProxyAgentexplicitly. - Credentials in the URL (
http://user:pass@proxy:3128) work but end up in process listings and logs of your tooling; prefer a secret store. - Failures look like ordinary network errors (
ECONNREFUSED,ENOTFOUND) naming the proxy, which can confuse debugging. Check the variables first when only some machines fail. - Version note: support for the environment proxy variables arrived in the Node 24 line; on older releases use an explicit agent or a library.