Seamless Cypress Installation Guide | Cypress Documentation (2024)


What you'll learn

  • How to install Cypress via npm, yarn or pnpm
  • 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.


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.


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.


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


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.


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.


Direct downloading for old versions

It is possible to download an old version from our CDN by suffixing the URL withthe desired version (ex.

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)


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.


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


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


  • 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.


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


pacman -S gtk2 gtk3 alsa-lib xorg-server-xvfb libxss nss libnotify


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

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!

Seamless Cypress Installation Guide | Cypress Documentation (2024)


Top Articles
Latest Posts
Article information

Author: Pres. Carey Rath

Last Updated:

Views: 6032

Rating: 4 / 5 (41 voted)

Reviews: 88% of readers found this page helpful

Author information

Name: Pres. Carey Rath

Birthday: 1997-03-06

Address: 14955 Ledner Trail, East Rodrickfort, NE 85127-8369

Phone: +18682428114917

Job: National Technology Representative

Hobby: Sand art, Drama, Web surfing, Cycling, Brazilian jiu-jitsu, Leather crafting, Creative writing

Introduction: My name is Pres. Carey Rath, I am a faithful, funny, vast, joyous, lively, brave, glamorous person who loves writing and wants to share my knowledge and understanding with you.