Skip to content
Tutorials Center
My learning

Topics

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.

NODE
// shell: NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://proxy.internal:3128 node app.js

Try it

Node.js Requests going through a proxy

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.

Node.js NO_PROXY and the default

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
// 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 as axios or got may 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 to localhost, add localhost,127.0.0.1 to 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 (see NODE_EXTRA_CA_CERTS if the proxy inspects TLS).
  • Read at startup. Set the variables in the environment of the process rather than assigning process.env later.
  • Applies to http and https requests that use the default agent. A custom agent you pass in is in charge of its own connections. Whether fetch() follows the variables depends on the Node release; the demos here use http, so test fetch() on your version or give undici an EnvHttpProxyAgent explicitly.
  • 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.