Skip to main content
Cypress App

Advanced Installation

Most people install Cypress with a single npm install cypress --save-dev and never need anything on this page. The defaults are designed to "just work": Cypress downloads the right binary for your operating system, caches it so it can be reused across projects, and launches it when you run a test.

This guide is for the situations where those defaults don't fit. It exists because real-world environments are messy: corporate proxies, air-gapped CI, locked-down certificate stores, disk-constrained build agents, and containerized editors all change how (and whether) Cypress can reach the internet and where it can write files. Each setting below is an escape hatch for one of those constraints.

info
What you'll learn​
  • How Cypress installs the npm module and the binary, and why that split matters
  • How to install a custom version, URL, or local file, or skip the binary entirely
  • How to install behind a proxy, download mirror, custom URL template, or custom certificate authority
  • How to relocate, inspect, and prune the binary cache
  • How to opt out of crash reports and commercial messaging
  • How to set up Cypress in WSL, Dev Containers, and GitHub Codespaces

How Cypress installs​

Understanding the install model makes almost every setting on this page self-explanatory. Installing Cypress happens in two distinct steps:

  1. The npm module (cypress) is added to your project like any other dependency. This package is small: it's the CLI, TypeScript types, and the cypress binary launcher. It is not the Cypress application itself.
  2. The binary (the actual Cypress application, including the bundled browsers' automation layer) is downloaded in a postinstall step. Because the binary is large and platform-specific, it is stored in a global cache outside node_modules so a single download can be shared by every project on the machine.

When you later run cypress open or cypress run, the npm module locates the matching binary in the cache and launches it.

This two-step model is the "why" behind most of the variables below:

  • Because the binary is downloaded separately, you can point that download at a different version, URL, or local file. See Install binary.
  • Because it comes over the network, restricted environments need a way to route through a proxy, a mirror, or a custom CA.
  • Because it lives in a shared cache, you can relocate, inspect, and prune that cache. See Binary cache.

Environment variables​

Almost every behavior on this page is driven by a system-level (OS) environment variable. These are set in your shell, CI configuration, or .npmrc.

NameDescription
CYPRESS_INSTALL_BINARYSets which Cypress binary to install: a version, URL, or local file
CYPRESS_DOWNLOAD_MIRRORDownloads the Cypress binary from a mirror server
CYPRESS_DOWNLOAD_PATH_TEMPLATEBuilds a custom URL to download the Cypress binary from
CYPRESS_CACHE_FOLDERChanges the location of the Cypress binary cache
CYPRESS_RUN_BINARYSets the path to the Cypress binary to launch at run time
CYPRESS_VERIFY_TIMEOUTOverrides the timeout duration for the verify command. The default value is 30000.
CYPRESS_SKIP_VERIFYSkips the verify command when set to true

When you'd reach for each​

The descriptions above say what each variable does. Here is the problem each one typically solves, so you can find the right tool for your situation:

  • CYPRESS_INSTALL_BINARY: Use this when the binary npm would install isn't the one you want. Common goals: pin a binary version that differs from the npm package, install from an internal URL when download.cypress.io is blocked, or install from a local .zip on an offline machine. Setting it to 0 skips the binary download entirely, which is handy for building base Docker images or splitting install and download into separate, debuggable steps.
  • CYPRESS_DOWNLOAD_MIRROR: Use this when your network blocks the public download server but you host an internal copy of it. It swaps the download host for your mirror while keeping the same URL layout, so many machines can install without each pinning a one-off URL.
  • CYPRESS_DOWNLOAD_PATH_TEMPLATE: Use this when your internal artifact store doesn't match the download.cypress.io URL layout. It lets you describe exactly how your server lays out files so Cypress can build the correct URL per platform and version.
  • CYPRESS_CACHE_FOLDER: Use this to control where the downloaded binary is stored. The most common goal is faster CI: point it at a directory your CI provider caches between runs so the download becomes a cache hit. It's also useful on locked-down machines where the default cache location isn't writable.
  • CYPRESS_RUN_BINARY: Use this when you want to launch a specific binary already on disk instead of the one resolved from the cache, for example a binary you unzipped to a known location.
  • CYPRESS_VERIFY_TIMEOUT: Use this to adjust how long Cypress waits for the one-time binary verification step before timing out. The default is 30 seconds (30000 ms); raise it on slow or heavily loaded machines where verification needs more time.
  • CYPRESS_SKIP_VERIFY: Use this to skip binary verification, for example when the binary lives in a read-only location and verification can't write its results.

Setting variables via npm config or package.json​

You don't have to export a shell variable to configure these options. This is valuable because shell exports don't persist across machines or CI agents, whereas committing the setting to your repo does, so the whole team and your CI get the same behavior automatically.

Every CYPRESS_* variable above can be set as a real environment variable, or through your npm configuration. Cypress resolves each variable in the following order, using the first value it finds:

  1. The actual environment variable (e.g. CYPRESS_INSTALL_BINARY)
  2. npm_config_<name> (set via .npmrc or npm config)
  3. The lowercase npm_config_<name>
  4. npm_package_config_<name> (set via a config block in package.json)

This means options like CYPRESS_INSTALL_BINARY, CYPRESS_CACHE_FOLDER, and CYPRESS_DOWNLOAD_MIRROR can all be configured in .npmrc:

.npmrc
cypress_install_binary=https://company.domain.com/cypress.zip
cypress_cache_folder=/path/to/cypress/cache
cypress_download_mirror=https://company.domain.com

or in a config block of your package.json:

package.json
{
  "config": {
    "cypress_install_binary": "https://company.domain.com/cypress.zip",
    "cypress_cache_folder": "/path/to/cypress/cache",
    "cypress_download_mirror": "https://company.domain.com"
  }
}

Proxy configuration​

Corporate networks frequently force outbound traffic through a proxy. Because the binary download happens outside your application code (in npm's postinstall), Cypress reads the proxy settings npm and the OS already use, so you usually don't have to configure anything Cypress-specific.

System proxy properties http_proxy, https_proxy and no_proxy are respected for the download of the Cypress binary. You can also use the npm properties npm_config_proxy and npm_config_https_proxy. Those have lower priority, so they will only be used if the system properties are being resolved to not use a proxy.

Install binary​

CYPRESS_INSTALL_BINARY controls which binary the postinstall step fetches. People most often need this when the version published to npm isn't the one they want, or when the public download server isn't reachable from where they're installing.

To override what is installed, you set CYPRESS_INSTALL_BINARY alongside the npm install command.

This is helpful if you want to:

  • Override the installed binary version for a single install, without editing the cypress version committed in your package.json. This is useful for quickly testing a different version locally or in CI without changing committed files. 
    CYPRESS_INSTALL_BINARY=15.16.0 npm install
  • Specify an external URL (to bypass a corporate firewall). 
    CYPRESS_INSTALL_BINARY=https://company.domain.com/cypress.zip npm install cypress
  • Specify a file to install locally instead of using the internet. 
    CYPRESS_INSTALL_BINARY=/local/path/to/cypress.zip npm install cypress

In all cases, the fact that the binary was installed from a custom location is not saved in your package.json file. Every repeated installation needs to use the same environment variable to install the same binary. If you'd rather not repeat the variable each time, set it in npm config or package.json so it's applied automatically on every install.

Skipping installation​

Sometimes you want the npm module without the binary download, for example, to build a base Docker image and add the binary in a later layer, or to install the binary yourself with debug output. Setting CYPRESS_INSTALL_BINARY=0 skips the download entirely.

CYPRESS_INSTALL_BINARY=0 npm install

Now Cypress will skip its install phase once the npm module is installed.

Troubleshoot installation​

When an install fails, the useful output is usually hidden: package managers run postinstall in the background by default. The fix is to run cypress install on its own with debug logging enabled so you can see exactly where the download or unzip step breaks.

CYPRESS_INSTALL_BINARY=0 npm install cypress --save-dev
DEBUG=cypress:cli* npx cypress install

To set environment variables CYPRESS_INSTALL_BINARY and DEBUG in Windows CMD or PowerShell terminals, refer to examples in Print DEBUG Logs.

In Continuous Integration (CI) use the following commands to display debug logs from the Cypress binary installation:

DEBUG=cypress:cli* npm ci --foreground-scripts

Install pre-release version​

Occasionally you'll want to verify a fix or try a feature before it ships in an official release. The Cypress team may also ask you to install a pre-release to confirm that an issue you reported is resolved before it's released. Cypress publishes a pre-release binary for individual commits on develop, which you can install the same way as any custom binary.

  1. Open up the list of commits to develop on the Cypress repo: https://github.com/cypress-io/cypress/commits/develop
  2. Find the commit that you would like to install the pre-release version of. Click the comment icon (highlighted in red below):
    Example of a commit for which pre-releases are available. Comment link highlighted in red.
  3. You should see several comments from the cypress-bot user with instructions for installing Cypress pre-releases. Pick the one that corresponds to your operating system and CPU architecture, and follow the instructions there to install the pre-release.

The cypress-bot comments point at pre-release binaries hosted on the Cypress CDN. If you are scripting pre-release installs, the URLs follow this pattern:

https://cdn.cypress.io/beta/binary/<version>/<platform>-<arch>/<branch>-<sha>/cypress.zip
  • <version>: the Cypress version being built (e.g. 15.16.0)
  • <platform>-<arch>: one of the supported platform/architecture combinations (e.g. darwin-arm64, linux-x64)
  • <branch>: the branch the binary was built from (e.g. develop)
  • <sha>: the full commit SHA

You can install a pre-release binary directly by pointing CYPRESS_INSTALL_BINARY at one of these URLs:

CYPRESS_INSTALL_BINARY=https://cdn.cypress.io/beta/binary/15.16.0/darwin-arm64/develop-abcdef1234567890/cypress.zip npm install cypress

Cypress pre-releases are only available for 60 days after they are built. Do not rely on these being available past 60 days.

Installing behind a firewall or mirror​

These sections all address the same root problem: the machine running npm install can't download from https://download.cypress.io directly. The simplest fix is to allowlist the URLs Cypress needs. If that isn't possible, host the binary yourself and point Cypress at it with a known download URL, a full mirror, a custom URL layout, or a private certificate authority.

Allowlist URLs for installation​

If your VPN, firewall, or proxy only permits traffic to approved hosts, add the following to your allowlist so the binary can be downloaded during npm install:

URLPurpose
https://download.cypress.ioResolves the correct binary for your version and platform
https://cdn.cypress.ioServes the actual binary .zip (download requests redirect here, and pre-release binaries are hosted here)
https://registry.npmjs.orgInstalls the cypress npm package (or your configured npm registry)

If you also run tests against Cypress Cloud, you'll need to allow additional URLs. See the full list of subdomains to allow on a restrictive VPN.

Download URLs​

If you want to download a specific Cypress version for a given platform (Operating System), you can get it from our CDN. This is the building block for air-gapped installs: download the .zip once, host it internally, and point CYPRESS_INSTALL_BINARY at it.

The download server URL is https://download.cypress.io.

We currently have the following downloads available:

  • Windows 64-bit (?platform=win32&arch=x64)
  • Linux 64-bit (?platform=linux)
  • macOS 64-bit (?platform=darwin)

Here are the available download URLs:

See https://download.cypress.io/desktop.json for all available platforms.

MethodURLDescription
GET/desktopDownload Cypress at latest version (platform auto-detected)
GET/desktop.jsonReturns JSON containing latest available CDN destinations
GET/desktop?platform=p&arch=aDownload Cypress for a specific platform and/or architecture
GET/desktop/:versionDownload Cypress with a specified version
GET/desktop/:version?platform=p&arch=aDownload Cypress with a specified version and platform and/or architecture

Example of downloading Cypress 15.16.0 for Windows 64-bit:

https://download.cypress.io/desktop/15.16.0?platform=win32&arch=x64

Mirroring​

When many machines install Cypress from inside a restricted network, hosting a mirror is more maintainable than pinning every project to a one-off URL. Set CYPRESS_DOWNLOAD_MIRROR to replace the download server URL https://download.cypress.io with your own mirror.

For example:

CYPRESS_DOWNLOAD_MIRROR="https://www.example.com" cypress install

Cypress will then attempt to download a binary with this format: https://www.example.com/desktop/:version?platform=p&arch=a

Your mirror server must handle requests to /desktop/:version with platform and arch query parameters, and serve the appropriate Cypress binary as a .zip file.

Supported platform and architecture combinations:

platformarchNotes
linuxx64Linux Intel/AMD 64-bit
linuxarm64Linux ARM64 (e.g. AWS Graviton, Apple Silicon containers)
darwinx64macOS Intel
darwinarm64macOS Apple Silicon
win32x64Windows; also used for ARM64 Windows (no native ARM64 binary)

On Windows ARM64 machines, Cypress automatically substitutes arm64 with x64 when building the download URL, so your mirror will only ever receive win32 requests with arch=x64.

On macOS, Cypress detects the machine's real architecture rather than relying on process.arch. If an x64 build of Node is running under Rosetta on Apple Silicon, Cypress still requests the native darwin-arm64 binary. This is why the downloaded architecture can differ from process.arch (which would report x64), and your mirror may receive arch=arm64 requests from an x64 Node process.

If your mirror uses a different URL structure than download.cypress.io, use CYPRESS_DOWNLOAD_PATH_TEMPLATE together with CYPRESS_DOWNLOAD_MIRROR. See Download path template for examples.

Download path template​

A plain mirror assumes your server mimics the download.cypress.io layout. CYPRESS_DOWNLOAD_PATH_TEMPLATE removes that assumption: it lets you describe exactly how your artifact store lays out files, so Cypress can build the right URL for the platform and version being installed.

The following replacements are supported:

PlaceholderReplaced withExample
${endpoint}The full base URL, including the version pathhttps://download.cypress.io/desktop/15.16.0
${platform}The platform being installed onwin32, linux, darwin
${arch}The architecture being installed onx64, arm64 (always x64 on Windows ARM64)
${version}The version number being installed15.16.0

${endpoint} expands to <base>/desktop/<version>. If CYPRESS_DOWNLOAD_MIRROR is set, its value is used as <base> instead of https://download.cypress.io, but /desktop/<version> is still appended.

Examples:​

To install the binary from a download mirror that matches the exact file structure of https://cdn.cypress.io:

export CYPRESS_DOWNLOAD_MIRROR=https://cypress-download.local
export CYPRESS_DOWNLOAD_PATH_TEMPLATE='${endpoint}/${platform}-${arch}/cypress.zip'

Example of a resulting URL: https://cypress-download.local/desktop/15.16.0/linux-x64/cypress.zip

To install the binary from a download server with a custom file structure:

export CYPRESS_DOWNLOAD_PATH_TEMPLATE='${endpoint}/${platform}-${arch}/cypress.zip'

Example of a resulting URL: https://software.local/cypress/linux/x64/15.16.0/cypress.zip

To define CYPRESS_DOWNLOAD_PATH_TEMPLATE in .npmrc, put a backslash before every $:

.npmrc
CYPRESS_DOWNLOAD_PATH_TEMPLATE=\${endpoint}/\${platform}-\${arch}/cypress.zip

Using a custom certificate authority (CA)​

Networks that intercept TLS (or serve downloads from an internal host with a private certificate) will cause the download to fail certificate validation. Pointing Cypress at your organization's CA lets the download succeed without disabling TLS verification.

Cypress can be configured to use the ca and cafile options from your npm config file to download the Cypress binary.

For example, to use the CA at /home/person/certs/ca.crt when downloading Cypress, add the following to your .npmrc:

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

Alternatively, you can supply the certificate inline with the ca option instead of pointing to a file. This is equivalent to setting the npm_config_ca environment variable. Newlines in the PEM certificate are represented with \n:

.npmrc
ca="-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----"

To supply more than one certificate, set ca to an array of strings. The same value can also be provided through the environment:

export npm_config_ca="-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----"

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 certificate authority when downloading the Cypress binary.

Note that the npm config is used as a replacement, and the node environment variable is used as an extension.

Binary cache​

Once downloaded, the binary lives in a global cache so it can be reused across projects and CI runs instead of being re-downloaded every time. Knowing where that cache is (and being able to move it) is what makes Cypress fast in CI and predictable on shared machines.

By default, global cache folders are:

  • MacOS: ~/Library/Caches/Cypress
  • Linux: ~/.cache/Cypress
  • Windows: /AppData/Local/Cypress/Cache

The most common reason to relocate the cache is CI caching: pointing CYPRESS_CACHE_FOLDER at a directory your CI provider persists between runs turns a multi-minute download into a cache hit. Set the environment variable to override the default:

export CYPRESS_CACHE_FOLDER=~/Desktop/cypress_cache

Cypress will automatically replace the ~ with the user's home directory. So you can pass CYPRESS_CACHE_FOLDER as a string from CI configuration files, for example:

environment:
  CYPRESS_CACHE_FOLDER: '~/.cache/Cypress'

If you use Bun, BUN_INSTALL_CACHE_DIR controls Bun's package cache and is independent of CYPRESS_CACHE_FOLDER, which stores the Cypress binary.

See also Continuous Integration - Caching section in the documentation.

caution

CYPRESS_CACHE_FOLDER will need to exist every time cypress is launched. To ensure this, consider exporting this environment variable. For example, in a .bash_profile (MacOS, Linux), or using RegEdit (Windows).

Managing the binary cache​

Over time the cache accumulates a binary per Cypress version you've used, which can quietly consume disk space on CI agents and developer machines. The cypress cache command lets you inspect and prune it. Run these with the appropriate package manager prefix described in How to run commands.

CommandDescription
cypress cache listLists the cached Cypress versions. Add --size to also report each version's size.
cypress cache pathPrints the path to the Cypress binary cache.
cypress cache pruneDeletes every cached binary except the version currently in use.
cypress cache clearDeletes all cached Cypress binaries.

Run binary​

CYPRESS_RUN_BINARY is the run-time counterpart to the install-time settings above: it tells the npm module to launch a specific binary on disk instead of the one it would normally resolve from the cache. This is useful when you've unzipped a binary to a known location and want to run it directly.

CYPRESS_RUN_BINARY should be a path to an already unzipped Cypress binary executable. The Cypress commands open, run and verify will then launch the provided binary.

The following example cypress run commands assume that you have first downloaded the Cypress binary to the default Downloads directory of your operating system.

Depending on how you then unzip the downloaded Cypress binary cypress.zip file, using a CLI command or alternatively a GUI interface, the directory structure may include one additional top-level directory named cypress, which you may need to add to the path defined by CYPRESS_RUN_BINARY.

If available, use the following to avoid the additional top-level directory level:

unzip -q cypress
note

The examples below are for npm. If you are using Yarn or pnpm as package manager, replace npx with yarn or pnpm as appropriate. See How to run commands.

CYPRESS_RUN_BINARY=~/Downloads/Cypress.app/Contents/MacOS/Cypress npx cypress run

Cypress assumes that CYPRESS_RUN_BINARY points to a writeable directory structure so that it can save and re-use the results of verifying the Cypress binary. If you encounter a permission denied failure message from cypress verify, you may be able to work around the failure by setting the environment variable CYPRESS_SKIP_VERIFY to true.

export CYPRESS_SKIP_VERIFY=true

Privacy and messaging​

Cypress sends a small amount of data outbound and occasionally surfaces commercial messages. Both are off-switches you may want in privacy-sensitive or noise-sensitive environments.

Opt out of sending exception data to Cypress​

When an exception is thrown regarding Cypress, we send along the exception data to https://api.cypress.io. We solely use this information to help develop a better product.

If you would like to opt out of sending any exception data to Cypress, you can do so by setting CYPRESS_CRASH_REPORTS=0 in your system environment variables. Set the variable before installing Cypress, using the approach for your operating system. To make this permanent, add the command to your shell's ~/.profile (for example, ~/.zshprofile or ~/.bash_profile) so it runs on every login.

export CYPRESS_CRASH_REPORTS=0

Opt out of Cypress commercial messaging​

Cypress may occasionally display messages in your CI logs related to our commercial offerings and how they could benefit you during your workflows.

If you would like to opt out of all commercial messaging, you can do so by setting CYPRESS_COMMERCIAL_RECOMMENDATIONS=0 in your system environment variables.

export CYPRESS_COMMERCIAL_RECOMMENDATIONS=0

Environment-specific setup​

These environments need extra setup because they don't provide a graphical display the way a normal desktop OS does, which is what the interactive Test Runner needs.

Windows Subsystem for Linux​

Cypress requires an X-server (X11) to display the Cypress UI from a Windows Subsystem for Linux installation. This requirement is met by current versions of Windows Subsystem for Linux (WSL2) with X11 support being included through Windows Subsystem for Linux GUI (WSLg).

Refer to GitHub: Windows Subsystem for Linux GUI (WSLg) for installation instructions on Ubuntu and install the prerequisite Linux packages before running Cypress.

Refer to Microsoft Learn Windows Subsystem for Linux Documentation for additional information.

info

Cypress.io does not specifically support the use of Cypress under Windows Subsystem for Linux (WSL). If you want to report an issue, please ensure that you can reproduce it without using WSL on one of the Cypress supported operating systems.

Dev Containers and GitHub Codespaces​

Dev Containers (VS Code Dev Containers) and GitHub Codespaces provide containerized Linux development environments.

Running tests headlessly with cypress run works without any extra display configuration when the container image includes the required Linux prerequisites. The official Cypress Docker images already include all prerequisites.

Running the interactive Test Runner with cypress open requires a graphical display, which containers do not provide by default. The simplest solution is the desktop-lite Dev Container feature, which installs a lightweight browser-accessible desktop inside the container.

Add the feature to your devcontainer.json and forward the necessary ports:

devcontainer.json
{
  "image": "cypress/included",
  "forwardPorts": [6080, 5901],
  "features": {
    "ghcr.io/devcontainers/features/desktop-lite:1": {}
  },
  "portsAttributes": {
    "6080": {
      "label": "desktop"
    }
  },
  "postCreateCommand": "npm install && cypress install"
}

After rebuilding the container, open http://localhost:6080 in your browser and log in with the default password vscode. Running cypress open in the terminal will display the Cypress UI in that browser-based desktop.

Replace cypress/included with the specific Cypress Docker image tag that matches your required Cypress and Node.js versions (for example, cypress/included:14.0.0).

caution

Cypress.io does not specifically support the use of Cypress in Dev Containers or GitHub Codespaces. If you want to report an issue, please ensure that you can reproduce it without a containerized environment on one of the Cypress supported operating systems.

Uninstall Cypress​

Removing Cypress is two-sided because of the install model: uninstalling the npm module removes it from your project, but the cached binaries and app data persist on disk until you remove them too.

To uninstall Cypress from a project, use the same package manager you used to install Cypress:

npm uninstall cypress

To uninstall all cached Cypress binary versions, use the cypress cache clear command with the appropriate package manager prefix described in How to run commands. To remove only the older cached versions while keeping the one currently in use, use cypress cache prune instead. Alternatively, delete the Cypress binary cache (see above) manually. See Managing the binary cache for the full set of cache commands.

To delete cached Cypress App Data, manually delete the following directories / folders:

  • macOS: ~/Library/Application Support/Cypress
  • Linux: ~/.config/Cypress
  • Windows: $APPDATA/Cypress (POSIX-syntax) or %APPDATA%\Cypress (Windows-syntax)

Refer to your package manager documentation for details of package manager cache clean commands to remove other packages cached by npm, Yarn, pnpm or Bun.

See also​

Contents