Skip to main content
Cypress App

Proxy Configuration

Why configure a proxy​

Cypress needs Internet access to work. In many organizations that access is only available through a corporate proxy. Until Cypress knows about that proxy, it can't reach the sites and services it depends on, so several features fail, often with confusing errors:

  • Cypress can't load any web pages other than localhost.
  • Cypress can't warn you when your baseUrl is unavailable.
  • Cypress can't connect to Cypress Cloud to log in or record test runs.
  • npm install cypress can fail while downloading the Cypress binary.

Proxy settings come into play at two distinct moments, and keeping them separate makes the rest of this page much clearer:

  • Installation: when npm install / cypress install downloads Cypress.
  • Running tests: when the Cypress app loads your application and communicates with Cypress Cloud.

Some settings apply to only one of these phases. That difference is a common source of "it installs but won't run" (or the reverse) confusion, so it is called out throughout this page.

Supported proxy types​

Cypress works with standard HTTP and HTTPS proxies. There are two exceptions to be aware of before you start:

Proxy Auto-Configuration (PAC) files are not supported. If your organization uses a PAC file, contact a network administrator to ask which HTTP proxy you should use to access the general Internet, then use that proxy with Cypress.

SOCKS proxies are not supported. As a workaround, set up a local HTTP proxy that points to your SOCKS proxy, then use that HTTP proxy with Cypress. Read more about forwarding an HTTP proxy through SOCKS.

Set a proxy​

The quickest way to get started is to set the HTTP_PROXY environment variable in a terminal before running Cypress. Select your operating system below:

export HTTP_PROXY=http://my-company-proxy.com

You can also set NO_PROXY to bypass the proxy for additional domains (loopback addresses such as localhost are always bypassed):

export NO_PROXY=localhost,google.com,apple.com

The commands above set the proxy for the current terminal session only. To make the change permanent on macOS or Linux, add the export commands to your shell's ~/.profile (~/.zsh_profile, ~/.bash_profile, etc.) so they run on every login. On Windows, use setx to save the variable for all new shells:

Windows
setx HTTP_PROXY http://my-company-proxy.com
info

Windows registry

On Windows, the proxy configured in the Windows registry is used as a fallback: Cypress only consults it when no proxy has been set through the HTTP_PROXY/HTTPS_PROXY environment variables or your npm config. When the registry value is used, the single configured proxy is applied to both HTTP_PROXY and HTTPS_PROXY. Learn how to set your proxy settings system-wide in Windows.

The registry fallback only applies when running your tests. When downloading Cypress for the first time, the cypress command line tool does not read proxy settings from the Windows registry. If you need a proxy for the installation to work, you must set the environment variables shown above. This is also the only way to define a proxy for cypress install.

How Cypress selects a proxy​

Cypress looks in several places for your proxy and uses the first one it finds. The sources it checks, and the certificate authority (CA) sources it trusts, differ between installation and running tests:

PhaseProxy resolution order (first match wins)Custom CA sources
Installation (binary download)HTTP_PROXY / HTTPS_PROXYnpm cafile, ca
Running testsHTTP_PROXY / HTTPS_PROXY → npm proxy / https-proxy → Windows registrynpm cafile, ca, NODE_EXTRA_CA_CERTS

Two practical takeaways:

  • Environment variables always win. Setting HTTP_PROXY / HTTPS_PROXY explicitly overrides every other source.
  • The Windows registry and NODE_EXTRA_CA_CERTS are only used when running tests, never during installation. If your binary download is blocked or TLS-intercepted, you must rely on environment variables and npm's cafile / ca.

The sections below describe each of these sources in detail.

Proxy environment variables​

caution

This section refers to your operating system's environment variables, not Cypress environment variables.

Cypress automatically reads from your system's HTTP_PROXY environment variable and uses that proxy for all HTTP and HTTPS traffic. If an HTTPS_PROXY environment variable is set, HTTPS traffic will use that proxy instead.

Setting HTTP_PROXY to a falsy value (false, 0, or an empty string) disables the proxy entirely. This is useful to turn off a proxy that is otherwise configured through your npm config or the Windows registry.

If the HTTP_PROXY and HTTPS_PROXY environment variables are not set, Cypress falls back to your npm proxy configuration when running your tests. npm exposes its proxy and https-proxy config values as the npm_config_proxy and npm_config_https_proxy environment variables, and Cypress applies them as follows:

npm configurationUsed asCondition
npm_config_proxyHTTP_PROXYif HTTP_PROXY unset
npm_config_https_proxyHTTPS_PROXYif HTTPS_PROXY unset

A proxy set through the HTTP_PROXY or HTTPS_PROXY environment variable always takes precedence over the corresponding npm configuration. Only npm's proxy and https-proxy values are used as a fallback. npm's noproxy configuration is not applied to NO_PROXY, so set NO_PROXY directly if you need to bypass the proxy for specific domains.

Bypassing the proxy with NO_PROXY​

To bypass the proxy for certain domains, set the NO_PROXY environment variable to a comma-separated list of domain names that should not be proxied.

Cypress always appends 127.0.0.1, ::1, and localhost to NO_PROXY so that loopback traffic is never proxied. This happens even when you set your own NO_PROXY entries; your list is added to, not replaced. The only way to send loopback traffic through the proxy is to include the special <-loopback> value in NO_PROXY, which removes the automatic loopback entries.

Casing​

If an uppercase and a lowercase version of a proxy setting are both supplied (for example, HTTP_PROXY and http_proxy), the lowercase variable is preferred.

Using a custom certificate authority (CA)​

caution

This section refers to npm config variables and Node environment variables, not Cypress environment variables.

When connecting through a proxy, a self-signed certificate is often used as a CA, and Cypress must trust it to authenticate with Cypress Cloud. When running your tests, Cypress automatically reads from npm config's cafile and ca options and the NODE_EXTRA_CA_CERTS Node environment variable.

To mimic the behavior of npm and Node, Cypress looks at cafile first and then ca, using the corresponding certificate(s) as a replacement for the CA. For example, to use the CA at /home/person/certs/ca.crt, add the following to your .npmrc:

.npmrc
cafile=/home/person/certs/ca.crt

If neither cafile nor ca is set, Cypress looks at the NODE_EXTRA_CA_CERTS environment variable and uses the corresponding certificate(s) as an extension of the trusted CAs.

caution

NODE_EXTRA_CA_CERTS does not apply to the binary download

The behavior above applies when Cypress runs your tests. The install-time binary download (cypress install) only reads npm's cafile and ca config values (via the npm_config_cafile and npm_config_ca environment variables). It does not read NODE_EXTRA_CA_CERTS.

If your binary download is being TLS-intercepted by a proxy that uses a custom CA, set cafile (or ca) in your .npmrc so that the download can complete. Setting NODE_EXTRA_CA_CERTS alone will not help at install time.

View proxy settings in Cypress​

Once configured, you can confirm which proxy Cypress is actually using.

From the Cypress app, open your project with cypress open, click the Settings tab, then expand the Proxy Settings section to view the proxy Cypress is currently using:

Proxy configuration in the Desktop app

You can also check your proxy settings from the command line. Running cypress info prints the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY values Cypress detects, which is a useful alternative to the Settings UI, especially in CI or other headless environments:

npx cypress info

Managing operating system environment variables​

Configuring a proxy often means viewing, setting, and clearing environment variables. The commands below show how to do that for the current session and permanently, per operating system. On Windows, the syntax differs between Command Prompt and PowerShell, so both are shown.

Set an environment variable for the current session​

export SOME_VARIABLE=some-value

Set an environment variable for all future sessions​

echo 'export SOME_VARIABLE=some-value' >> ~/.profile

Unset an environment variable​

unset SOME_VARIABLE

On macOS or Linux, echo $SOME_VARIABLE will print nothing once the variable has been unset.

See all the currently set environment variables​

caution

Avoid in CI environments

Do not print environment variables in CI runs where logs are captured and stored, as this can expose sensitive information like passwords, API keys, or tokens that may be stored in environment variables.

env

See the environment variables containing "proxy"​

env | grep -i proxy

See also​

Contents