--- id: app/configure/proxy-configuration title: Proxy configuration in Cypress description: >- Why Cypress needs proxy configuration behind a corporate proxy, how it resolves your proxy settings, and how to configure them on macOS, Linux, and Windows section: app source_path: docs/app/configure/proxy-configuration.mdx version: 2069658b67bb86b8923569761b9bda5eebc57aff updated_at: '2026-08-25T16:55:04.655Z' --- # Proxy Configuration 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`](/llm/markdown/app/references/configuration.md#Global) is unavailable. * Cypress can't connect to [Cypress Cloud](/llm/markdown/cloud/get-started/introduction.md) 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.](https://superuser.com/questions/423563/convert-http-requests-to-socks5) ## 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: * macOS * Linux * Windows ``` export HTTP_PROXY=http://my-company-proxy.com ``` ``` export HTTP_PROXY=http://my-company-proxy.com ``` Command Prompt ``` set HTTP_PROXY=http://my-company-proxy.com ``` PowerShell ``` $env: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): * macOS * Linux * Windows ``` export NO_PROXY=localhost,google.com,apple.com ``` ``` export NO_PROXY=localhost,google.com,apple.com ``` Command Prompt ``` set NO_PROXY=localhost,google.com,apple.com ``` PowerShell ``` $env: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 ``` **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.](https://www.howtogeek.com/tips/how-to-set-your-proxy-settings-in-windows-8.1/) 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: | Phase | Proxy resolution order (first match wins) | Custom CA sources | | --- | --- | --- | | Installation (binary download) | `HTTP_PROXY` / `HTTPS_PROXY` | npm `cafile`, `ca` | | Running tests | `HTTP_PROXY` / `HTTPS_PROXY` → npm `proxy` / `https-proxy` → Windows registry | npm `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 This section refers to your operating system's environment variables, _not_ [Cypress environment variables](/llm/markdown/app/guides/environment-variables.md). 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`](https://docs.npmjs.com/cli/v9/using-npm/config#proxy) and [`https-proxy`](https://docs.npmjs.com/cli/v9/using-npm/config#https-proxy) config values as the `npm_config_proxy` and `npm_config_https_proxy` environment variables, and Cypress applies them as follows: | npm configuration | Used as | Condition | | --- | --- | --- | | `npm_config_proxy` | `HTTP_PROXY` | if `HTTP_PROXY` unset | | `npm_config_https_proxy` | `HTTPS_PROXY` | if `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`](https://docs.npmjs.com/cli/v9/using-npm/config#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) This section refers to npm config variables and Node environment variables, _not_ [Cypress environment variables](/llm/markdown/app/guides/environment-variables.md). 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](/llm/markdown/cloud/get-started/introduction.md). When **running your tests**, Cypress automatically reads from npm config's [`cafile`](https://docs.npmjs.com/cli/v8/using-npm/config#cafile) and [`ca`](https://docs.npmjs.com/cli/v8/using-npm/config#ca) options and the [`NODE_EXTRA_CA_CERTS`](https://nodejs.org/api/cli.html#node_extra_ca_certsfile) 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. **`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: 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: * npm * Yarn * pnpm * Bun ``` npx cypress info ``` ``` yarn cypress info ``` ``` pnpm cypress info ``` ``` bunx 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 * macOS * Linux * Windows ``` export SOME_VARIABLE=some-value ``` ``` export SOME_VARIABLE=some-value ``` Command Prompt ``` set SOME_VARIABLE=some-value ``` PowerShell ``` $env:SOME_VARIABLE = "some-value" ``` ### Set an environment variable for all future sessions * macOS * Linux * Windows ``` echo 'export SOME_VARIABLE=some-value' >> ~/.profile ``` ``` echo 'export SOME_VARIABLE=some-value' >> ~/.profile ``` ``` setx SOME_VARIABLE some-value ``` ### Unset an environment variable * macOS * Linux * Windows ``` unset SOME_VARIABLE ``` ``` unset SOME_VARIABLE ``` Command Prompt ``` set SOME_VARIABLE= ``` PowerShell ``` Remove-Item Env:\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 **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. * macOS * Linux * Windows ``` env ``` ``` env ``` Command Prompt ``` set ``` PowerShell ``` Get-ChildItem Env: ``` ### See the environment variables containing "proxy" * macOS * Linux * Windows ``` env | grep -i proxy ``` ``` env | grep -i proxy ``` Command Prompt ``` set | findstr /I proxy ``` PowerShell ``` Get-ChildItem Env: | Where-Object Name -Match 'proxy' ``` ## See also * [Environment Variables](/llm/markdown/app/guides/environment-variables.md) * [Configuration](/llm/markdown/app/references/configuration.md) * [Command Line](/llm/markdown/app/references/command-line.md) * [Cypress Cloud](/llm/markdown/cloud/get-started/introduction.md)