info
What you'll learn
- How to install Cypress via
npm,yarnorpnpm - How to install Cypress via direct download
- How to version and run Cypress via
package.json
First, make sure you have all the system requirements.
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.
info
Make sure you have Node.js installed and that you have already runnpm init or have a node_modules folder orpackage.json file in the root of your project to ensure cypress is installedin the correct directory.
info
System proxy properties http_proxy, https_proxy and no_proxy are respectedfor the download of the Cypress binary. You can also use the npm propertiesnpm_config_proxy and npm_config_https_proxy. Those have lower priority, sothey will only be used if the system properties are being resolved to not use aproxy.
Best Practice
The recommended approach is to install Cypress with npm because:
- Cypress is versioned like any other dependency.
- It simplifies running Cypress inContinuous Integration.
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 respectedfor the download of the Cypress binary.
pnpm add
Installing Cypress via pnpm:
cd /your/project/path
pnpm add --save-dev cypress
info
You need to make sure that you have the pnpm environment installed locally.If not you need to install it: npm install pnpm@latest --global.
Direct download
If you're not using Node or a package manager (npm, pnpm or Yarn) in your project or you want to try Cypress outquickly, you can alwaysdownload Cypress directly from our CDN.
caution
Recording runs to Cypress Cloud is not possible from the direct download. Thisdownload is only intended as a quick way to try out Cypress. To record tests toCypress Cloud, you'll need to install Cypress as an npm dependency.
The direct download will always grab the latest available version. Your platformwill be detected automatically.
Then you can manually unzip and double click. Cypress will run without needingto install any dependencies.
info
Direct downloading for old versions
It is possible to download an old version from our CDN by suffixing the URL withthe 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 orjust need help with troubleshooting, check out ourAdvanced Installation reference.
Continuous integration
Please read ourContinuous Integration docs forhelp installing Cypress in CI. When running in Linux you may need to install somesystem dependenciesor you can use our Docker images which have everything youneed prebuilt.
System requirements
Operating System
Cypress is a desktop application that is installed on your computer. The desktopapplication 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 38 and above, and Debian 10 and above (x64 or arm64) (see Linux Prerequisites downbelow)
- Windows 10 and above (64-bit only)
Node.js
Cypress requires Node.js in order to install. We support the versions listed below:
- Node.js 18.x
- Node.js 20.x and above
Cypress generally aligns withNode's release schedule.
Hardware
When running Cypress locally, it should run comfortably on any machine that iscapable of modern web development.
When running Cypress in CI, however, some of the lower-tier configurations mightnot be able to run Cypress reliably, especially when recording videos or doinglonger test runs.
Some issues you might run into in CI that could be a sign of insufficientresources are:
- Exiting early during
cypress runor 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 hardwarerequirements:
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 installedon 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.Cypress Docker images, which are Debian-based, already include the necessary dependencies.
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 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
CentOS
yum install -y xorg-x11-server-Xvfb gtk2-devel gtk3-devel libnotify-devel GConf2 nss libXScrnSaver alsa-lib
Amazon Linux 2023
dnf install -y xorg-x11-server-Xvfb gtk3-devel nss alsa-lib
Docker
Docker images with all of the required dependencies installed are availableunder cypress/base
If you're running your projects in containers, then you'll want Cypress in thecontainer with the Node.js process.
ui:
image: cypress/base:latest
# if targeting a specific node version, use e.g.
# image: cypress/base:18.12.1
cypress/base is a drop-in replacement forbase docker node images.
Great, now install Cypress!
Next Steps
Open the app and take it for a testdrive!
