{
  "doc": {
    "id": "app/references/proxy-configuration",
    "title": "Proxy Configuration in Cypress",
    "description": "How to configure Cypress to work with a corporate proxy",
    "section": "app",
    "source_path": "/llm/markdown/app/references/proxy-configuration.md",
    "version": "524ff5211e60b5d53e55d6ad976d83966f66e7cd",
    "updated_at": "2026-04-30T14:20:05.396Z",
    "headings": [
      {
        "id": "app/references/proxy-configuration#proxy-configuration",
        "text": "Proxy Configuration",
        "level": 1
      },
      {
        "id": "app/references/proxy-configuration#set-a-proxy-on-linux-or-macos",
        "text": "Set a proxy on Linux or macOS",
        "level": 2
      },
      {
        "id": "app/references/proxy-configuration#set-a-proxy-on-windows",
        "text": "Set a proxy on Windows",
        "level": 2
      },
      {
        "id": "app/references/proxy-configuration#proxy-environment-variables",
        "text": "Proxy environment variables",
        "level": 2
      },
      {
        "id": "app/references/proxy-configuration#using-a-custom-certificate-authority-ca",
        "text": "Using a custom certificate authority (CA)",
        "level": 2
      },
      {
        "id": "app/references/proxy-configuration#view-unset-and-set-environment-variables",
        "text": "View, unset, and set environment variables",
        "level": 2
      },
      {
        "id": "app/references/proxy-configuration#linux-or-macos",
        "text": "Linux or macOS",
        "level": 3
      },
      {
        "id": "app/references/proxy-configuration#set-an-environment-variable-for-the-current-session",
        "text": "Set an environment variable for the current session",
        "level": 4
      },
      {
        "id": "app/references/proxy-configuration#unset-an-environment-variable",
        "text": "Unset an environment variable",
        "level": 4
      },
      {
        "id": "app/references/proxy-configuration#see-all-the-currently-set-environment-variables",
        "text": "See all the currently set environment variables",
        "level": 4
      },
      {
        "id": "app/references/proxy-configuration#windows",
        "text": "Windows",
        "level": 3
      },
      {
        "id": "app/references/proxy-configuration#set-an-environment-variable-for-current-session",
        "text": "Set an environment variable for current session",
        "level": 4
      },
      {
        "id": "app/references/proxy-configuration#set-environment-variable-globally-for-all-future-sessions",
        "text": "Set environment variable globally for all future sessions",
        "level": 4
      },
      {
        "id": "app/references/proxy-configuration#unset-an-environment-variable-in-the-current-session",
        "text": "Unset an environment variable in the current session",
        "level": 4
      },
      {
        "id": "app/references/proxy-configuration#see-all-currently-set-environment-variables",
        "text": "See all currently set environment variables",
        "level": 4
      },
      {
        "id": "app/references/proxy-configuration#view-proxy-settings-in-cypress",
        "text": "View proxy settings in Cypress",
        "level": 2
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "Proxy Configuration"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Cypress needs Internet access to work. Many companies require the use of a corporate proxy to access the Internet. If your company does this, many functions of Cypress will not work until you've configured Cypress to use your proxy:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Cypress won't be able to load web pages besides `localhost`."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Cypress won't be able to warn you if your "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/configuration.md#Global",
                    "children": [
                      {
                        "type": "text",
                        "value": "baseUrl"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " isn't available."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Cypress won't be able to connect to "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/cloud/get-started/introduction.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Cypress Cloud"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " to log in or record test runs."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`npm install cypress` may fail while downloading the Cypress binary."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If you are experiencing any or all of these issues, you may need to configure Cypress with your proxy. Instructions are available for "
          },
          {
            "type": "link",
            "title": null,
            "url": "#Set-a-proxy-on-Linux-or-macOS",
            "children": [
              {
                "type": "text",
                "value": "macOS"
              }
            ]
          },
          {
            "type": "text",
            "value": ", "
          },
          {
            "type": "link",
            "title": null,
            "url": "#Set-a-proxy-on-Linux-or-macOS",
            "children": [
              {
                "type": "text",
                "value": "Linux"
              }
            ]
          },
          {
            "type": "text",
            "value": ", and "
          },
          {
            "type": "link",
            "title": null,
            "url": "#Set-a-proxy-on-Windows",
            "children": [
              {
                "type": "text",
                "value": "Windows"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Proxy Auto-Configuration (PAC) files are not currently supported. If your organization uses a PAC file, contact a network administrator to ask what HTTP proxy you should be using to access the general Internet, then use that proxy with Cypress."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "SOCKS proxies are not currently supported. A workaround is to set up an HTTP proxy locally that points to your SOCKS proxy, then using that HTTP proxy with Cypress. "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://superuser.com/questions/423563/convert-http-requests-to-socks5",
            "children": [
              {
                "type": "text",
                "value": "Read more about forwarding an HTTP proxy through SOCKS."
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Set a proxy on Linux or macOS"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "To set your proxy on Linux or macOS, run the following command in a terminal before running Cypress:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "export HTTP_PROXY=http://my-company-proxy.com"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can also set `NO_PROXY` to bypass the proxy for certain domains (by default, only `localhost` will be bypassed):"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "export NO_PROXY=localhost,google.com,apple.com"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "To make these changes permanent, you can add these commands to your shell's `~/.profile` (`~/.zsh_profile`, `~/.bash_profile`, etc.) to run them on every login."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Set a proxy on Windows"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When starting up after being installed, Cypress will attempt to load the proxy configured in the Windows registry by default. "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://www.howtogeek.com/tips/how-to-set-your-proxy-settings-in-windows-8.1/",
            "children": [
              {
                "type": "text",
                "value": "Learn how to set your proxy settings system-wide in Windows."
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When downloading Cypress for the first time, the `cypress` command line tool does not read proxy settings from the Windows registry. If you need to configure a proxy for the installation to work, you must set the appropriate environment variables as described below."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can also set proxy environment variables before running Cypress to override the Windows registry. This is also the only way to define a proxy for `cypress install`. In Command Prompt, defining the required environment variables looks like this:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "set HTTP_PROXY=http://my-company-proxy.com"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "To accomplish the same thing in PowerShell:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "$env:HTTP_PROXY = \"http://my-company-proxy.com\""
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "To save the `HTTP_PROXY` variable and use your proxy for all new shells, use `setx`:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "setx HTTP_PROXY http://my-company-proxy.com"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Proxy environment variables"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "This section refers to your operating system's environment variables, not "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/guides/environment-variables.md",
            "children": [
              {
                "type": "text",
                "value": "Cypress environment variables"
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "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."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "To bypass the proxy for certain domains, a `NO_PROXY` environment variable can be set to a comma-separated list of domain names to not proxy traffic for. By default, traffic to `localhost` will not be proxied. To make Cypress send traffic for `localhost` through the proxy, pass `<-loopback>` in `NO_PROXY`."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If an uppercase and a lowercase version of the proxy settings are supplied (for example, `HTTP_PROXY` and `http_proxy` are both set), the lowercase variable will be preferred."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Using a custom certificate authority (CA)"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "This section refers to npm config variables and node environment variables, not "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/guides/environment-variables.md",
            "children": [
              {
                "type": "text",
                "value": "Cypress environment variables"
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Cypress needs to be able to authenticate properly when communicating to "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/cloud/get-started/introduction.md",
            "children": [
              {
                "type": "text",
                "value": "Cypress Cloud"
              }
            ]
          },
          {
            "type": "text",
            "value": ". When connecting through a proxy, oftentimes a self signed certificate is used as a CA. In order to handle this configuration, Cypress automatically reads from npm config's "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://docs.npmjs.com/cli/v8/using-npm/config#cafile",
            "children": [
              {
                "type": "text",
                "value": "`cafile`"
              }
            ]
          },
          {
            "type": "text",
            "value": " and "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://docs.npmjs.com/cli/v8/using-npm/config#ca",
            "children": [
              {
                "type": "text",
                "value": "`ca`"
              }
            ]
          },
          {
            "type": "text",
            "value": " options and the "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://nodejs.org/api/cli.html#node_extra_ca_certsfile",
            "children": [
              {
                "type": "text",
                "value": "`NODE_EXTRA_CA_CERTS`"
              }
            ]
          },
          {
            "type": "text",
            "value": " node environment variable."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "To mimic the behavior of npm and node, Cypress looks at `cafile` first and then `ca` and uses 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`:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cafile=/home/person/certs/ca.crt"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If neither `cafile` nor `ca` are set, Cypress looks at the system environment variable `NODE_EXTRA_CA_CERTS` and uses the corresponding certificate(s) as an extension for the trusted CA."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Note that the npm config is used as a replacement, and the node environment variable is used as an extension."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "View, unset, and set environment variables"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "In order to properly configure your proxy configuration, it can be helpful to know how to view currently set environment variables, unset unwanted environment variables, and set environment variables depending on your operating system."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Linux or macOS"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Set an environment variable for the current session"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "export SOME_VARIABLE=some-value"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Unset an environment variable"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "unset SOME_VARIABLE"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`echo` will print nothing after `unset`:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "echo $SOME_VARIABLE"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "See all the currently set environment variables"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Avoid in CI environments"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "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."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Print all env vars:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "env"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Print environment variables with `proxy` (case insensitive) in the name:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "env | grep -i proxy"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Windows"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Setting environment variables in Windows is different depending on if you're using command prompt or PowerShell."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Set an environment variable for current session"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Command prompt:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "set SOME_VARIABLE=some-value"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "PowerShell:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "$env:SOME_VARIABLE = \"some-value\""
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Set environment variable globally for all future sessions"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "setx SOME_VARIABLE some-value"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Unset an environment variable in the current session"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Command prompt:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "set SOME_VARIABLE="
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "PowerShell:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "Remove-Item Env:\\SOME_VARIABLE"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "See all currently set environment variables"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Command prompt:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "set"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "PowerShell:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "Get-ChildItem Env:"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "View proxy settings in Cypress"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Your current proxy settings can be viewed from within Cypress. Follow these steps:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": true,
        "start": 1,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Open up your project in Cypress via `cypress open`."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Click the \"Settings\" tab."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Click the \"Proxy Settings\" section to expand it and view the proxy settings that Cypress is currently using."
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "token_estimate": 1340
}