Advanced Installation

info

What you'll learn

How to install Cypress with a custom binary
How to skip the installation of the Cypress binary
How to change the Cypress binary cache location or download URL
How to use a custom certificate authority (CA)
How to opt out of sending exception data to Cypress

Environment variables

Name	Description
`CYPRESS_INSTALL_BINARY`	Destination of Cypress binary that's downloaded and installed
`CYPRESS_CONNECT_RETRY_THRESHOLD`	Overrides the maximum number of retries when connecting to a browser. The default value is 62.
`CYPRESS_DOWNLOAD_MIRROR`	Downloads the Cypress binary through a mirror server
`CYPRESS_DOWNLOAD_PATH_TEMPLATE`	Allows generating a custom URL to download the Cypress binary from
`CYPRESS_CACHE_FOLDER`	Changes the Cypress binary cache location
`CYPRESS_RUN_BINARY`	Location of Cypress binary at run-time
`CYPRESS_VERIFY_TIMEOUT`	Overrides the timeout duration for the `verify` command. The default value is 30000.
`CYPRESS_SKIP_VERIFY`	Skips the `verify` command (for stable CI environments)
~~CYPRESS_SKIP_BINARY_INSTALL~~	removed use `CYPRESS_INSTALL_BINARY=0` instead
~~CYPRESS_BINARY_VERSION~~	removed use `CYPRESS_INSTALL_BINARY` instead

Install binary

Using the CYPRESS_INSTALL_BINARY environment variable, you can control how Cypress is installed. To override what is installed, you set CYPRESS_INSTALL_BINARY alongside the npm install command.

This is helpful if you want to:

Install a version different than the default npm package.

CYPRESS_INSTALL_BINARY=13.7.0 npm install [email protected]

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.

Skipping installation

You can also force Cypress to skip the installation of the binary application by setting CYPRESS_INSTALL_BINARY=0. This could be useful if you want to prevent Cypress from downloading the Cypress binary at the time of npm install.

CYPRESS_INSTALL_BINARY=0 npm install

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

Troubleshoot installation

The Cypress Life Cycle script postinstall installs the Cypress binary after the Cypress npm module has been installed. Package managers however execute the postinstall step in the background by default which hides the debug output. Execute cypress install separately with debug logging enabled to view the debug logs.

npm
Yarn
pnpm

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

CYPRESS_INSTALL_BINARY=0 yarn add cypress --dev
DEBUG=cypress:cli* yarn cypress install

CYPRESS_INSTALL_BINARY=0 pnpm add --save-dev cypress
DEBUG=cypress:cli* pnpm 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:

npm
Yarn
pnpm

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

yarn install --frozen-lockfile --ignore-scripts # Yarn v1 Classic only
DEBUG=cypress:cli* yarn cypress install

pnpm install --frozen-lockfile --ignore-scripts
DEBUG=cypress:cli* pnpm cypress install

Binary cache

As of version 3.0, Cypress downloads the matching Cypress binary to the global system cache, so that the binary can be shared between projects. By default, global cache folders are:

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

To override the default cache folder, set the environment variable CYPRESS_CACHE_FOLDER.

CYPRESS_CACHE_FOLDER=~/Desktop/cypress_cache npm install

CYPRESS_CACHE_FOLDER=~/Desktop/cypress_cache npm run test

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'

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).

Run binary

Setting the environment variable CYPRESS_RUN_BINARY overrides where the npm module finds the Cypress binary.

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

Mac

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

Linux

CYPRESS_RUN_BINARY=~/Downloads/Cypress/Cypress cypress run

Windows

CYPRESS_RUN_BINARY=~/Downloads/Cypress/Cypress.exe cypress run

caution

We recommend not exporting the CYPRESS_RUN_BINARY environment variable, since it will affect every cypress module installed on your file system.

Download URLs

If you want to download a specific Cypress version for a given platform (Operating System), you can get it from our CDN.

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.

Method	URL	Description
`GET`	`/desktop`	Download Cypress at latest version (platform auto-detected)
`GET`	`/desktop.json`	Returns JSON containing latest available CDN destinations
`GET`	`/desktop?platform=p&arch=a`	Download Cypress for a specific platform and/or architecture
`GET`	`/desktop/:version`	Download Cypress with a specified version
`GET`	`/desktop/:version?platform=p&arch=a`	Download Cypress with a specified version and platform and/or architecture

Example of downloading Cypress 12.17.4 for Windows 64-bit:

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

Mirroring

If you choose to mirror the entire Cypress download site, you can specify CYPRESS_DOWNLOAD_MIRROR to set the download server URL from https://download.cypress.io to 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

Download path template

Starting with Cypress 9.3.0, you can use the CYPRESS_DOWNLOAD_PATH_TEMPLATE environment variable to download the Cypress binary from a custom URL that's generated based on endpoint, version, platform and architecture.

The following replacements are supported:

${endpoint} is replaced with https://download.cypress.io/desktop/:version. If CYPRESS_DOWNLOAD_MIRROR is set, its value is used instead of https://download.cypress.io (note that the /desktop remains!)
${platform} is replaced with the platform the installation is running on (e.g. win32, linux, darwin)
${arch} is replaced with the architecture the installation is running on (e.g. x64, arm64)
Starting with Cypress 10.6.0, ${version} is replaced with the version number that's being installed (e.g. 10.11.0)

Examples:

To install the binary from a download mirror that matches the exact file structure of https://cdn.cypress.io (works for Cypress 9.3.0 or newer):

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/10.11.0/linux-x64/cypress.zip

To install the binary from a download server with a custom file structure (works for Cypress 10.6.0 or newer):

export CYPRESS_DOWNLOAD_PATH_TEMPLATE='https://software.local/cypress/${platform}/${arch}/${version}/cypress.zip'
# Example of a resulting URL: https://software.local/cypress/linux/x64/10.11.0/cypress.zip

To define CYPRESS_DOWNLOAD_PATH_TEMPLATE in .npmrc, put a backslash before every $ (works for Cypress 9.5.3 or newer):

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

Using a custom certificate authority (CA)

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:

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

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.

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.

Opt out on Linux or macOS

To opt out of sending exception data on Linux or macOS, run the following command in a terminal before installing Cypress:

export CYPRESS_CRASH_REPORTS=0

To make these changes permanent, you can add this command to your shell's ~/.profile (~/.zsh_profile, ~/.bash_profile, etc.) to run them on every login.

Opt out on Windows

To opt out of sending exception data on Windows, run the following command in the Command Prompt before installing Cypress:

set CYPRESS_CRASH_REPORTS=0

To accomplish the same thing in PowerShell:

$env:CYPRESS_CRASH_REPORTS = "0"

To save the CYPRESS_CRASH_REPORTS variable for use in all new shells, use setx:

setx 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.

Install pre-release version

If you would like to install a pre-release version of Cypress to test out functionality that has not yet been released, here is how:

Open up the list of commits to develop on the Cypress repo: https://github.com/cypress-io/cypress/commits/develop
Find the commit that you would like to install the pre-release version of. Click the comment icon (highlighted in red below):
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.

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

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.

Uninstall Cypress

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

npm
Yarn
pnpm

npm uninstall cypress

yarn remove cypress

pnpm remove 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. Alternatively, delete the Cypress binary cache (see above) manually.

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 or pnpm.

What you'll learn​

Environment variables​

Install binary​

Skipping installation​

Troubleshoot installation​

Binary cache​

Run binary​

Mac​

Linux​

Windows​

Download URLs​

Mirroring​

Download path template​

Using a custom certificate authority (CA)​

Opt out of sending exception data to Cypress​

Opt out on Linux or macOS​

Opt out on Windows​

Opt out of Cypress commercial messaging​

Install pre-release version​

Windows Subsystem for Linux​

Uninstall Cypress​

Contents