Install Cypress
What you'll learnβ
- How to install Cypress using npm, yarn, or pnpm
- System requirements for Cypress
- How to install Cypress using direct download
- Advanced installation options
Installing Cypress
First, make sure you have all the system requirements.
Installβ
Install Cypress via your preferred package manager. This will install Cypress locally as a dev dependency for your project. For pnpm, make sure that you have the pnpm
environment installed: npm install pnpm@latest --global
.
- npm
- yarn
- pnpm
npm install cypress --save-dev
yarn add cypress --dev
pnpm add --save-dev cypress
Make sure you have Node.js installed and that you have already run
npm init
or have a node_modules
folder or
package.json
file in the root of your project to ensure Cypress is installed
in the correct directory.
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.
The Node.js Snap for Linux package manager has constrained operating system access. Install using:
npm install cypress --save-dev --foreground-scripts
Direct downloadβ
The recommended approach is to install Cypress with npm
because:
- Cypress is versioned like any other dependency.
- It simplifies running Cypress in Continuous Integration.
If you're not using Node or a package manager in your project or you want to just try Cypress out quickly, you can always download Cypress directly from our CDN.
Recording runs to Cypress Cloud is not possible from the direct download. This download is only intended as a quick way to try out Cypress. To record tests to Cypress Cloud, you'll need to install Cypress as an package dependency.
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.
It is possible to download an old version from our CDN by suffixing the URL with the desired version (ex. https://download.cypress.io/desktop/12.17.4).
Advanced Installationβ
If you have more complex requirements, want to level-up your Cypress workflow or just need help with troubleshooting, check out our Advanced Installation reference. You can also find instructions to uninstall Cypress in this reference documentation.
Continuous integrationβ
Please read our Continuous Integration docs for help installing Cypress in CI. When running in Linux you may need to install some system dependencies or you can use our Docker images which have everything you need prebuilt.
System requirementsβ
Operating Systemβ
Cypress is a desktop application that is installed on your computer. The desktop application supports these operating systems:
- macOS 10.15 and above (Intel or Apple Silicon 64-bit (x64 or arm64)).
- Linux Ubuntu 20.04 and above, Fedora 40 and above, and Debian 11 and above (x64 or arm64) (see Linux Prerequisites down below).
- Windows 10 and above (x64).
Node.jsβ
Cypress requires Node.js in order to install. We support the versions listed below:
- Node.js 18.x, 20.x, 22.x and above
Cypress generally aligns with Node's release schedule.
Installing Node.jsβ
Follow the instructions on Download Node.js to download and install Node.js.
If you are using a Cypress Docker image, you will find a fixed version of Node.js is pre-installed in the image. You select the Node.js version using the Docker image tag.
Use a Node.js package manager to install Node.js. Package managers for Node.js allow you to switch between different versions easily.
Hardwareβ
When running Cypress locally, it should run comfortably on any machine that is capable of modern web development.
When running Cypress in CI, however, some of the lower-tier configurations might not be able to run Cypress reliably, especially when recording videos or doing longer test runs.
Some issues you might run into in CI that could be a sign of insufficient resources are:
- Exiting early during
cypress run
or abruptly closing (βcrashingβ) - Frozen or missing frames in the video that is captured
- Increased runtime
When running Cypress in CI, we recommend that you have the following hardware requirements:
CPUβ
- 2 CPUs minimum to run Cypress
- 1 additional CPU if video recording is enabled
- 1 additional CPU per process you run outside of Cypress, such as:
- App server (frontend)
- App server (backend)
- App database
- Any additional infrastructure (Redis, Kafka, etc..)
Memoryβ
- 4GB minimum, 8GB+ for longer test runs
Linux Prerequisitesβ
If you're using Linux, you'll want to have the required dependencies installed on your system. Depending on your system defaults, these dependencies may already be installed. If not, run the command line for your operating system listed below. See below under Docker Prerequisites for information on Cypress Docker images. These already include the necessary dependencies.
It is worth noting that Cypress on Linux requires a minimum glibc
version of 2.17
. This version is fixed as glibc
is shipped with your operating system and cannot be changed.
Ubuntu/Debianβ
apt-get install libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev libnss3 libxss1 libasound2 libxtst6 xauth xvfb
For Ubuntu 24.04, and above, use the following command:
apt-get install libgtk2.0-0t64 libgtk-3-0t64 libgbm-dev libnotify-dev libnss3 libxss1 libasound2t64 libxtst6 xauth xvfb
Archβ
pacman -S gtk2 gtk3 alsa-lib xorg-server-xvfb libxss nss libnotify
Amazon Linux 2023β
dnf install -y xorg-x11-server-Xvfb gtk3-devel nss alsa-lib
Docker Prerequisitesβ
Cypress Docker images are available from Docker Hub and the Amazon ECR (Elastic Container Registry) Public Gallery. These images, which are Linux (Debian) based, include all of the required dependencies pre-installed.
If you need Node.js, browser or Cypress version combinations which are not covered by the published Cypress Docker images, then the cypress/factory image allows you to generate your own customized Docker image easily.
If you are not using a Cypress Docker image, make sure that your base operating system is a Linux system listed in the supported
Operating Systems above and that Node.js is installed in the image.
It is recommended to have unzip
installed. This avoids the Cypress binary installation falling back to a slower unzip method using Node.js.
Next Stepsβ
Open the app and take it for a test drive!