{
  "doc": {
    "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": "/llm/markdown/app/configure/proxy-configuration.md",
    "version": "e4f4d57da4cfedd520d3d465137d387fd54b532f",
    "updated_at": "2026-09-08T17:49:12.214Z",
    "headings": [
      {
        "id": "app/configure/proxy-configuration#proxy-configuration",
        "text": "Proxy Configuration",
        "level": 1
      },
      {
        "id": "app/configure/proxy-configuration#supported-proxy-types",
        "text": "Supported proxy types",
        "level": 2
      },
      {
        "id": "app/configure/proxy-configuration#set-a-proxy",
        "text": "Set a proxy",
        "level": 2
      },
      {
        "id": "app/configure/proxy-configuration#how-cypress-selects-a-proxy",
        "text": "How Cypress selects a proxy",
        "level": 2
      },
      {
        "id": "app/configure/proxy-configuration#proxy-environment-variables",
        "text": "Proxy environment variables",
        "level": 2
      },
      {
        "id": "app/configure/proxy-configuration#bypassing-the-proxy-with-no-proxy",
        "text": "Bypassing the proxy with NO_PROXY",
        "level": 3
      },
      {
        "id": "app/configure/proxy-configuration#casing",
        "text": "Casing",
        "level": 3
      },
      {
        "id": "app/configure/proxy-configuration#using-a-custom-certificate-authority-ca",
        "text": "Using a custom certificate authority (CA)",
        "level": 2
      },
      {
        "id": "app/configure/proxy-configuration#view-proxy-settings-in-cypress",
        "text": "View proxy settings in Cypress",
        "level": 2
      },
      {
        "id": "app/configure/proxy-configuration#managing-operating-system-environment-variables",
        "text": "Managing operating system environment variables",
        "level": 2
      },
      {
        "id": "app/configure/proxy-configuration#set-an-environment-variable-for-the-current-session",
        "text": "Set an environment variable for the current session",
        "level": 3
      },
      {
        "id": "app/configure/proxy-configuration#set-an-environment-variable-for-all-future-sessions",
        "text": "Set an environment variable for all future sessions",
        "level": 3
      },
      {
        "id": "app/configure/proxy-configuration#unset-an-environment-variable",
        "text": "Unset an environment variable",
        "level": 3
      },
      {
        "id": "app/configure/proxy-configuration#see-all-the-currently-set-environment-variables",
        "text": "See all the currently set environment variables",
        "level": 3
      },
      {
        "id": "app/configure/proxy-configuration#see-the-environment-variables-containing-proxy",
        "text": "See the environment variables containing \"proxy\"",
        "level": 3
      },
      {
        "id": "app/configure/proxy-configuration#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "chunks": [
    {
      "id": "app/configure/proxy-configuration#supported-proxy-types",
      "doc_id": "app/configure/proxy-configuration",
      "heading": "Supported proxy types",
      "heading_level": 2,
      "content_markdown": "## Supported proxy types\n\nCypress works with standard HTTP and HTTPS proxies. There are two exceptions to be aware of before you start:\n\n**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.\n\n**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)\n",
      "section": "app",
      "anchors": [
        "supported-proxy-types"
      ],
      "path": "/llm/json/chunked/app/configure/proxy-configuration.json",
      "token_estimate": 128
    },
    {
      "id": "app/configure/proxy-configuration#set-a-proxy",
      "doc_id": "app/configure/proxy-configuration",
      "heading": "Set a proxy",
      "heading_level": 2,
      "content_markdown": "## Set a proxy\n\nThe quickest way to get started is to set the `HTTP_PROXY` environment variable in a terminal before running Cypress. Select your operating system below:\n\n*   macOS\n*   Linux\n*   Windows\n\n```\nexport HTTP_PROXY=http://my-company-proxy.com\n```\n\n```\nexport HTTP_PROXY=http://my-company-proxy.com\n```\n\nCommand Prompt\n\n```\nset HTTP_PROXY=http://my-company-proxy.com\n```\n\nPowerShell\n\n```\n$env:HTTP_PROXY = \"http://my-company-proxy.com\"\n```\n\nYou can also set `NO_PROXY` to bypass the proxy for additional domains (loopback addresses such as `localhost` are always bypassed):\n\n*   macOS\n*   Linux\n*   Windows\n\n```\nexport NO_PROXY=localhost,google.com,apple.com\n```\n\n```\nexport NO_PROXY=localhost,google.com,apple.com\n```\n\nCommand Prompt\n\n```\nset NO_PROXY=localhost,google.com,apple.com\n```\n\nPowerShell\n\n```\n$env:NO_PROXY = \"localhost,google.com,apple.com\"\n```\n\nThe 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:\n\nWindows\n\n```\nsetx HTTP_PROXY http://my-company-proxy.com\n```\n\n**Windows registry**\n\nOn 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/)\n\nThe 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`.\n",
      "section": "app",
      "anchors": [
        "set-a-proxy"
      ],
      "path": "/llm/json/chunked/app/configure/proxy-configuration.json",
      "token_estimate": 372
    },
    {
      "id": "app/configure/proxy-configuration#how-cypress-selects-a-proxy",
      "doc_id": "app/configure/proxy-configuration",
      "heading": "How Cypress selects a proxy",
      "heading_level": 2,
      "content_markdown": "## How Cypress selects a proxy\n\nCypress 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:\n\n| Phase | Proxy resolution order (first match wins) | Custom CA sources |\n| --- | --- | --- |\n| Installation (binary download) | `HTTP_PROXY` / `HTTPS_PROXY` | npm `cafile`, `ca` |\n| Running tests | `HTTP_PROXY` / `HTTPS_PROXY` → npm `proxy` / `https-proxy` → Windows registry | npm `cafile`, `ca`, `NODE_EXTRA_CA_CERTS` |\n\nTwo practical takeaways:\n\n*   **Environment variables always win.** Setting `HTTP_PROXY` / `HTTPS_PROXY` explicitly overrides every other source.\n*   **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`.\n\nThe sections below describe each of these sources in detail.\n",
      "section": "app",
      "anchors": [
        "how-cypress-selects-a-proxy"
      ],
      "path": "/llm/json/chunked/app/configure/proxy-configuration.json",
      "token_estimate": 207
    },
    {
      "id": "app/configure/proxy-configuration#proxy-environment-variables",
      "doc_id": "app/configure/proxy-configuration",
      "heading": "Proxy environment variables",
      "heading_level": 2,
      "content_markdown": "## Proxy environment variables\n\nThis section refers to your operating system's environment variables, _not_ [Cypress environment variables](/llm/markdown/app/guides/environment-variables.md).\n\nCypress 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.\n\nSetting `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.\n\nIf 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:\n\n| npm configuration | Used as | Condition |\n| --- | --- | --- |\n| `npm_config_proxy` | `HTTP_PROXY` | if `HTTP_PROXY` unset |\n| `npm_config_https_proxy` | `HTTPS_PROXY` | if `HTTPS_PROXY` unset |\n\nA 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.\n\n### Bypassing the proxy with `NO_PROXY`\n\nTo 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.\n\nCypress 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.\n\n### Casing\n\nIf 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.\n",
      "section": "app",
      "anchors": [
        "proxy-environment-variables"
      ],
      "path": "/llm/json/chunked/app/configure/proxy-configuration.json",
      "token_estimate": 437
    },
    {
      "id": "app/configure/proxy-configuration#bypassing-the-proxy-with-no-proxy",
      "doc_id": "app/configure/proxy-configuration",
      "heading": "Bypassing the proxy with NO_PROXY",
      "heading_level": 3,
      "content_markdown": "### Bypassing the proxy with `NO_PROXY`\n\nTo 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.\n\nCypress 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.\n",
      "section": "app",
      "anchors": [
        "bypassing-the-proxy-with-no-proxy"
      ],
      "path": "/llm/json/chunked/app/configure/proxy-configuration.json",
      "token_estimate": 117
    },
    {
      "id": "app/configure/proxy-configuration#using-a-custom-certificate-authority-ca",
      "doc_id": "app/configure/proxy-configuration",
      "heading": "Using a custom certificate authority (CA)",
      "heading_level": 2,
      "content_markdown": "## Using a custom certificate authority (CA)\n\nThis section refers to npm config variables and Node environment variables, _not_ [Cypress environment variables](/llm/markdown/app/guides/environment-variables.md).\n\nWhen 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.\n\nTo 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`:\n\n.npmrc\n\n```\ncafile=/home/person/certs/ca.crt\n```\n\nIf 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.\n\n**`NODE_EXTRA_CA_CERTS` does not apply to the binary download**\n\nThe 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`.\n\nIf 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.\n",
      "section": "app",
      "anchors": [
        "using-a-custom-certificate-authority-ca"
      ],
      "path": "/llm/json/chunked/app/configure/proxy-configuration.json",
      "token_estimate": 288
    },
    {
      "id": "app/configure/proxy-configuration#view-proxy-settings-in-cypress",
      "doc_id": "app/configure/proxy-configuration",
      "heading": "View proxy settings in Cypress",
      "heading_level": 2,
      "content_markdown": "## View proxy settings in Cypress\n\nOnce configured, you can confirm which proxy Cypress is actually using.\n\nFrom 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:\n\nYou 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:\n\n*   npm\n*   Yarn\n*   pnpm\n*   Bun\n\n```\nnpx cypress info\n```\n\n```\nyarn cypress info\n```\n\n```\npnpm cypress info\n```\n\n```\nbunx cypress info\n```\n",
      "section": "app",
      "anchors": [
        "view-proxy-settings-in-cypress"
      ],
      "path": "/llm/json/chunked/app/configure/proxy-configuration.json",
      "token_estimate": 149
    },
    {
      "id": "app/configure/proxy-configuration#managing-operating-system-environment-variables",
      "doc_id": "app/configure/proxy-configuration",
      "heading": "Managing operating system environment variables",
      "heading_level": 2,
      "content_markdown": "## Managing operating system environment variables\n\nConfiguring 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.\n\n### Set an environment variable for the current session\n\n*   macOS\n*   Linux\n*   Windows\n\n```\nexport SOME_VARIABLE=some-value\n```\n\n```\nexport SOME_VARIABLE=some-value\n```\n\nCommand Prompt\n\n```\nset SOME_VARIABLE=some-value\n```\n\nPowerShell\n\n```\n$env:SOME_VARIABLE = \"some-value\"\n```\n\n### Set an environment variable for all future sessions\n\n*   macOS\n*   Linux\n*   Windows\n\n```\necho 'export SOME_VARIABLE=some-value' >> ~/.profile\n```\n\n```\necho 'export SOME_VARIABLE=some-value' >> ~/.profile\n```\n\n```\nsetx SOME_VARIABLE some-value\n```\n\n### Unset an environment variable\n\n*   macOS\n*   Linux\n*   Windows\n\n```\nunset SOME_VARIABLE\n```\n\n```\nunset SOME_VARIABLE\n```\n\nCommand Prompt\n\n```\nset SOME_VARIABLE=\n```\n\nPowerShell\n\n```\nRemove-Item Env:\\SOME_VARIABLE\n```\n\nOn macOS or Linux, `echo $SOME_VARIABLE` will print nothing once the variable has been unset.\n\n### See all the currently set environment variables\n\n**Avoid in CI environments**\n\nDo 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.\n\n*   macOS\n*   Linux\n*   Windows\n\n```\nenv\n```\n\n```\nenv\n```\n\nCommand Prompt\n\n```\nset\n```\n\nPowerShell\n\n```\nGet-ChildItem Env:\n```\n\n### See the environment variables containing \"proxy\"\n\n*   macOS\n*   Linux\n*   Windows\n\n```\nenv | grep -i proxy\n```\n\n```\nenv | grep -i proxy\n```\n\nCommand Prompt\n\n```\nset | findstr /I proxy\n```\n\nPowerShell\n\n```\nGet-ChildItem Env: | Where-Object Name -Match 'proxy'\n```\n",
      "section": "app",
      "anchors": [
        "managing-operating-system-environment-variables"
      ],
      "path": "/llm/json/chunked/app/configure/proxy-configuration.json",
      "token_estimate": 367
    },
    {
      "id": "app/configure/proxy-configuration#set-an-environment-variable-for-the-current-session",
      "doc_id": "app/configure/proxy-configuration",
      "heading": "Set an environment variable for the current session",
      "heading_level": 3,
      "content_markdown": "### Set an environment variable for the current session\n\n*   macOS\n*   Linux\n*   Windows\n\n```\nexport SOME_VARIABLE=some-value\n```\n\n```\nexport SOME_VARIABLE=some-value\n```\n\nCommand Prompt\n\n```\nset SOME_VARIABLE=some-value\n```\n\nPowerShell\n\n```\n$env:SOME_VARIABLE = \"some-value\"\n```\n",
      "section": "app",
      "anchors": [
        "set-an-environment-variable-for-the-current-session"
      ],
      "path": "/llm/json/chunked/app/configure/proxy-configuration.json",
      "token_estimate": 47
    },
    {
      "id": "app/configure/proxy-configuration#set-an-environment-variable-for-all-future-sessions",
      "doc_id": "app/configure/proxy-configuration",
      "heading": "Set an environment variable for all future sessions",
      "heading_level": 3,
      "content_markdown": "### Set an environment variable for all future sessions\n\n*   macOS\n*   Linux\n*   Windows\n\n```\necho 'export SOME_VARIABLE=some-value' >> ~/.profile\n```\n\n```\necho 'export SOME_VARIABLE=some-value' >> ~/.profile\n```\n\n```\nsetx SOME_VARIABLE some-value\n```\n",
      "section": "app",
      "anchors": [
        "set-an-environment-variable-for-all-future-sessions"
      ],
      "path": "/llm/json/chunked/app/configure/proxy-configuration.json",
      "token_estimate": 45
    },
    {
      "id": "app/configure/proxy-configuration#unset-an-environment-variable",
      "doc_id": "app/configure/proxy-configuration",
      "heading": "Unset an environment variable",
      "heading_level": 3,
      "content_markdown": "### Unset an environment variable\n\n*   macOS\n*   Linux\n*   Windows\n\n```\nunset SOME_VARIABLE\n```\n\n```\nunset SOME_VARIABLE\n```\n\nCommand Prompt\n\n```\nset SOME_VARIABLE=\n```\n\nPowerShell\n\n```\nRemove-Item Env:\\SOME_VARIABLE\n```\n\nOn macOS or Linux, `echo $SOME_VARIABLE` will print nothing once the variable has been unset.\n",
      "section": "app",
      "anchors": [
        "unset-an-environment-variable"
      ],
      "path": "/llm/json/chunked/app/configure/proxy-configuration.json",
      "token_estimate": 60
    },
    {
      "id": "app/configure/proxy-configuration#see-all-the-currently-set-environment-variables",
      "doc_id": "app/configure/proxy-configuration",
      "heading": "See all the currently set environment variables",
      "heading_level": 3,
      "content_markdown": "### See all the currently set environment variables\n\n**Avoid in CI environments**\n\nDo 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.\n\n*   macOS\n*   Linux\n*   Windows\n\n```\nenv\n```\n\n```\nenv\n```\n\nCommand Prompt\n\n```\nset\n```\n\nPowerShell\n\n```\nGet-ChildItem Env:\n```\n",
      "section": "app",
      "anchors": [
        "see-all-the-currently-set-environment-variables"
      ],
      "path": "/llm/json/chunked/app/configure/proxy-configuration.json",
      "token_estimate": 89
    },
    {
      "id": "app/configure/proxy-configuration#see-the-environment-variables-containing-proxy",
      "doc_id": "app/configure/proxy-configuration",
      "heading": "See the environment variables containing \"proxy\"",
      "heading_level": 3,
      "content_markdown": "### See the environment variables containing \"proxy\"\n\n*   macOS\n*   Linux\n*   Windows\n\n```\nenv | grep -i proxy\n```\n\n```\nenv | grep -i proxy\n```\n\nCommand Prompt\n\n```\nset | findstr /I proxy\n```\n\nPowerShell\n\n```\nGet-ChildItem Env: | Where-Object Name -Match 'proxy'\n```\n",
      "section": "app",
      "anchors": [
        "see-the-environment-variables-containing-proxy"
      ],
      "path": "/llm/json/chunked/app/configure/proxy-configuration.json",
      "token_estimate": 61
    }
  ]
}