Installation

Install & Run​

1. Check Requirements: make sure you meet thesystem requirements includingoperating system, installation of Node.js and a supported package manager.
2. Run in your project root: This will install Cypress locally as a dev dependency for your project.

npm install cypress --save-dev

yarn add cypress --dev

pnpm add --save-dev cypress

3. Open Cypress: This launches the Cypress App so you can choose end-to-end (E2E) or component testing (CT) and start writing tests.

npx cypress open

yarn cypress open

pnpm cypress open

4. Write your first test: Start withE2E orComponent Testing.

System requirements​

Operating System​

Cypress supports running under these operating systems:

• macOS >=13.5(Intel or Apple Silicon 64-bit (x64 or arm64))
• Linux(x64 or arm64) see alsoLinux Prerequisites down below
  • Ubuntu >=22.04
  • Debian >=11
  • Fedora >=42
• Windows 10 & 11(x64)
• Windows 11 24H2(arm64, runs inx64 emulation mode, minimum Cypress14.5.0 required) - preview status
• Windows Server 2019, 2022 and 2025(x64)

Node.js​

• Node.js 20.x, 22.x, >=24.x

Follow the instructions onDownload Node.js to download and installNode.js.

If you're using aCypress Docker image, you'll find a fixed version of Node.js is pre-installed in the image. You select the Node.js version using the Docker image tag.

Package Manager​

Cypress is installed using one of the following supported package managers:

Yarn users​

Yarn (Modern) configuration usingnodeLinker: "node-modules"is preferred. CypressComponent Testing is not currently compatible with the default settingnodeLinker: "pnp" which usesYarn Plug'n'Play.

pnpm configuration​

The following configuration options enable Cypress to execute itspostinstall script so it can install the Cypress binary into thebinary cache.If these configuration options are not set, then Cypress may skip thepostinstall script execution and Cypress will not run.

The pnpmside effects cache uses and caches the results of (pre/post)install hooks and is not compatible with Cypress' own caching.Disable the pnpmside effects cache, for example using the following command, executed in the root of your Cypress project:

pnpm config set side-effects-cache false --location project

[email protected] and above require allowlistingcypress.Refer to thepnpm settings documentation for additional information.In[email protected] and above, the CLIadd option--allow-build can be used, for example:

pnpm --allow-build=cypress add --save-dev cypress

Browsers​

Each Cypress release includes the Electron-bundled Chromiumbrowser.

The latest 3 major versions of the following browsers are also supported:

• Google Chrome
• Microsoft Edge
• Mozilla Firefox (Firefox >=141.0 requires Cypress >=14.1.0)
• WebKit support is experimental

Hardware​

• Local: Any modern dev machine works
• CI: At least 2 CPUs + 4 GB RAM (8 GB+ recommended for long runs or video recording)

Some issues you might run into in CI that could be a sign of insufficient resources are:

• Exiting early duringcypress run or abruptly closing ("crashing")
• Frozen or missing frames in the video
• Increased runtime

Linux Prerequisites​

Install required dependencies. See below underDocker Prerequisites for information onCypress Docker images. These already include the necessary dependencies.

Ubuntu/Debian​

For Ubuntu 22.04 and Debian:

apt-get install libgtk-3-0 libgbm-dev libnotify-dev libnss3 libxss1 libasound2 libxtst6 xauth xvfb

For Ubuntu >=24.04 and optionally for Debian 13:

apt-get install libgtk-3-0t64 libgbm-dev libnotify-dev libnss3 libxss1 libasound2t64 libxtst6 xauth xvfb

Arch​

pacman -S 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 fromDocker Hub and theAmazon 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 thecypress/factory imageallows 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 supportedOperating Systems above and that Node.js is installed in the image.It is recommended to haveunzip installed. This avoids the Cypress binary installation falling back to a slower unzip method using Node.js.

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.You can also find instructions touninstall Cypress in this reference documentation.

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 ourDocker images which have everything youneed prebuilt.

Next Steps​

Open the app and take it for a test drive!