Installing Cypress

System requirements

Operating System

Cypress is a desktop application that is installed on your computer. The desktop application supports these operating systems:

• macOS 10.9 and above (64-bit only)
• Linux Ubuntu 12.04 and above, Fedora 21 and Debian 8 (64-bit only)
• Windows 7 and above (64-bit only)

Node.js

If you're using npm to install Cypress, we support:

• Node.js 12 or 14 and above

Linux

If you're using Linux, you'll want to have the required dependencies installed on your system.

Ubuntu/Debian

apt-get install libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2 libxtst6 xauth xvfb

CentOS

yum install -y xorg-x11-server-Xvfb gtk2-devel gtk3-devel libnotify-devel GConf2 nss libXScrnSaver alsa-lib

Docker

Docker images with all of the required dependencies installed are available under cypress/base

If you're running your projects in containers, then you'll want Cypress in the container with the Node.js process.

  ui:
    image: cypress/base:latest
    # if targeting a specific node version, use e.g.
    # image: cypress/base:14

cypress/base is a drop-in replacement for base docker node images.

Installing

npm install

Install Cypress via npm:

cd /your/project/path

npm install cypress --save-dev

This will install Cypress locally as a dev dependency for your project.

yarn add

Installing Cypress via yarn:

cd /your/project/path

yarn add cypress --dev

System proxy properties http_proxy, https_proxy and no_proxy are respected for the download of the Cypress binary.

Direct download

If you're not using Node or npm in your project or you want to try Cypress out quickly, you can always download Cypress directly from our CDN.

The direct download will always grab the latest available version. Your platform will be detected automatically.

Then you can manually unzip and double click. Cypress will run without needing to install any dependencies.

Continuous integration

Please read our Continuous Integration docs for help installing Cypress in CI. When running in linux you'll need to install some system dependencies or you can use our Docker images which have everything you need prebuilt.

Opening Cypress

If you used npm to install, Cypress has now been installed to your ./node_modules directory, with its binary executable accessible from ./node_modules/.bin.

Now you can open Cypress from your project root one of the following ways:

The long way with the full path

./node_modules/.bin/cypress open

Or with the shortcut using npm bin

$(npm bin)/cypress open

Or by using npx

note: npx is included with npm > v5.2 or can be installed separately.

npx cypress open

Or by using yarn

yarn run cypress open

After a moment, the Cypress Test Runner will launch.

Switching browsers

The Cypress Test Runner attempts to find all compatible browsers on the user's machine. The drop down to select a different browser is in the top right corner of the Test Runner.

Read Launching Browsers for more information on how Cypress controls a real browser during end-to-end tests.

Adding npm scripts

While there's nothing wrong with writing out the full path to the Cypress executable each time, it's much easier and clearer to add Cypress commands to the scripts field in your package.json file.

{
  "scripts": {
    "cypress:open": "cypress open"
  }
}

Now you can invoke the command from your project root like so:

npm run cypress:open

...and Cypress will open right up for you.

CLI tools

By installing Cypress through npm you also get access to many other CLI commands.

As of version 0.20.0 Cypress is also a fully baked node_module you can require in your Node scripts.

You can read more about the CLI here.

Advanced

Environment variables

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. shell CYPRESS_INSTALL_BINARY=2.0.1 npm install cypress@2.0.3
• Specify an external URL (to bypass a corporate firewall). shell CYPRESS_INSTALL_BINARY=https://company.domain.com/cypress.zip npm install cypress
• Specify a file to install locally instead of using the internet. shell 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.

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.

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

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.

Example of downloading Cypress 3.0.0 for Windows 64-bit:

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

When setting CYPRESS_DOWNLOAD_PATH_TEMPLATE='${endpoint}/${platform}-${arch}/cypress.zip' environment variable, then a custom download url is used, where ${endpoint}, ${platform}, ${arch} are replaced with respective values.

https://download.cypress.io/desktop/3.0.0/win32-x64/cypress.zip

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

Using a custom 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:

CYPRESS_DOWNLOAD_USE_CA=1
ca=/home/person/certs/ca.crt

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

Install pre-release version

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

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

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

WSL2

First, install the prerequisite packages using the command that relates to your linux distribution (Ubuntu/Debian or CentOS).

We need to have an X-server to display the Cypress UI from the linux subsystem. There are a variety of X-servers available, here we are going to use VcXsrv, you can use any other similar tool.

Download VcXsrv and install. You can set the settings to your preference ("Multiple windows" and "Start no client" are recommended), but on the page that lets you enable extra settings, be sure to select "Disable access control" which is required as WSL2 has its own IP address, which changes often.

In your .bashrc (or equivalent such as .zshrc) set the DISPLAY environment variable.

# set DISPLAY variable to the IP automatically assigned to WSL2
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2; exit;}'):0.0

To confirm DISPLAY variable has been set, print it out in the terminal. You may need to restart your terminal to see this change.

echo $DISPLAY
# something like 172.17.224.1:0.0

The VcXsrv GUI uses D-Bus to internally communicate. After the export DISPLAY line in your .bashrc, add the following:

sudo /etc/init.d/dbus start &> /dev/null

Now your user needs to be granted access to run sudo dbus without needing to enter a password. To do so, use the visido command:

sudo visudo -f /etc/sudoers.d/dbus

In the editor that launches, add the following line, replacing <your_username> with your username (you can use the whoami command to print your username if you don't know it).

<your_username> ALL = (root) NOPASSWD: /etc/init.d/dbus

Go to Control Panel > System and Security > Windows Defender Firewall > Inbound Rules > New Rule.

Select Program and click on next. On the This program path, browse and select path to VcxSrv. On the next page select allow the connection and click next. On the next page, select all three options (Domain, Private, Public).

Give the rule a suitable name and description and click finish. WSL2 should now be able to open a GUI from shell.