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

Before installing Cypress, ensure you meet the system requirements, including:

A supported operating system
Installation of Node.js
A supported package manager

Install Cypress via Package Manager

You can install Cypress locally as a development dependency using your preferred package manager.

npm

npm install cypress --save-dev

yarn

yarn add cypress --dev

pnpm

pnpm add cypress --save-dev

Ensure you have a package.json file in the root of your project. If you don’t, create one using:

npm init -y

Proxy Support

System proxy properties http_proxy, https_proxy, and no_proxy are respected for downloading the Cypress binary. You can also use npm_config_proxy and npm_config_https_proxy as fallback options.

Direct Download

The recommended approach is installing Cypress via npm for:

Version management
Simplified CI/CD integration

However, if you don’t use Node.js, you can download Cypress directly from the CDN:

Cypress Direct Download

Limitations:

Recording runs to Cypress Cloud is not possible with the direct download.
Always downloads the latest available version.

For older versions, append the version to the URL:

https://download.cypress.io/desktop/12.17.4

Advanced Installation

For complex setups or troubleshooting, refer to the Advanced Installation guide.

For CI setups, check the Continuous Integration guide.

System Requirements

Supported Operating Systems

macOS: 10.15+ (Intel or Apple Silicon, x64/arm64)
Linux: Ubuntu 20.04+, Fedora 40+, Debian 11+ (x64/arm64)
Windows: 10+ (x64), Server 2019 & 2022

Node.js Compatibility

Node.js 18.x, 20.x, 22.x+
Cypress follows Node’s release schedule.

Installing Node.js

Download from Node.js official website.

Best Practice: Use a version manager like nvm to switch between Node versions easily.

Avoid: Using the Snap version on Linux, as it may cause permission issues.

Supported Package Managers

Package Manager	Version
npm	8.6.0+
Yarn 1 (Classic)	1.22.22+
Yarn (Modern)	4.x+
pnpm	8.x+

Yarn Configuration

For Yarn (Modern), use:

{"nodeLinker": "node-modules"}

Component Testing is not compatible with nodeLinker: "pnp".

If using Cypress Docker images, Node.js is pre-installed.

Hardware Requirements

Local Machine

Any system capable of modern web development

Continuous Integration (CI)

Resource	Minimum
CPU	2 CPUs (1 extra for video recording)
RAM	4GB (8GB+ for longer test runs)

CI Performance Issues

If Cypress runs into problems such as early exits or missing frames in videos, consider increasing CPU or RAM resources.

Linux Prerequisites

If using Linux, ensure these dependencies are installed:

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+:

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

Arch Linux:

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 provides Docker images with all dependencies pre-installed.

If you need a specific Node.js/browser/Cypress version, use the cypress/factory image.
Ensure your base OS is supported and install Node.js if not using Cypress Docker images.
Install unzip for faster binary installation.

Conclusion

This guide provides everything you need to install Cypress efficiently. For more details, refer to the official Cypress documentation.

Cypress part 2