--- id: app/get-started/install-cypress title: 'Install using npm, Yarn, or pnpm | Cypress Documentation' description: >- The fastest way to get Cypress running. Check requirements, install it in your project, and start testing today. section: app source_path: docs/app/get-started/install-cypress.mdx version: ce02913654e2655ee63448bdc92bb92c7b46a619 updated_at: '2026-04-22T19:37:51.587Z' --- # Installation ##### What you'll learn - How to install Cypress using npm, Yarn, or pnpm - What you need before installing - Advanced installation options ## Install & Run 1. **Check Requirements:** make sure you meet the [system requirements](#System-requirements) including operating 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. 3) **Open Cypress:** This launches the Cypress App so you can choose end-to-end (E2E) or component testing (CT) and start writing tests. 4. **Write your first test:** Start with [E2E](/llm/markdown/app/end-to-end-testing/writing-your-first-end-to-end-test.md) or [Component Testing](/llm/markdown/app/component-testing/get-started.md). ## 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 also [Linux Prerequisites](#Linux-Prerequisites) down below - Ubuntu >=22.04 - Debian >=11 - Fedora >=42 - **Windows** 10 & 11 *(x64)* - **Windows** 11 25H2 *(arm64, runs in [x64 emulation](https://learn.microsoft.com/en-us/windows/arm/apps-on-arm-x86-emulation) mode, minimum Cypress [14.5.0](/llm/markdown/app/references/changelog.md#14-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 on [Download Node.js](https://nodejs.org/en/download/) to download and install [Node.js](https://nodejs.org/). Note that the [Node.js Snap for Linux](https://github.com/nodejs/snap) version manager is not recommended for use with Cypress. Attempting to use it as a non-root user may result in permissions errors. If you're using a [Cypress Docker image](./continuous-integration/overview.md#Cypress-Docker-variants), 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: | Manager | Version | Docs | | ------------------------------------------------ | --------- | -------------------------------------------------------------------------------- | | [npm](https://docs.npmjs.com/) | >=10.1.0 | [Install npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) | | [Yarn 1 (Classic)](https://classic.yarnpkg.com/) | >=1.22.22 | [Install Yarn Classic](https://classic.yarnpkg.com/en/docs/install) | | [Yarn (Modern aka berry)](https://yarnpkg.com/) | >=4.x | [Install Yarn Modern](https://yarnpkg.com/getting-started/install) | | [pnpm](https://pnpm.io/) | >=8.x | [Install pnpm](https://pnpm.io/installation) | #### Yarn users [Yarn (Modern)](https://yarnpkg.com/) configuration using [nodeLinker: "node-modules"](https://yarnpkg.com/configuration/yarnrc#nodeLinker) is preferred. Cypress [Component Testing](/llm/markdown/app/core-concepts/testing-types.md#What-is-Component-Testing) is not currently compatible with the default setting [nodeLinker: "pnp"](https://yarnpkg.com/configuration/yarnrc#nodeLinker) which uses [Yarn Plug'n'Play](https://yarnpkg.com/features/pnp). #### pnpm configuration The following configuration options enable Cypress to execute its `postinstall` script so it can install the Cypress binary into the [binary cache](/llm/markdown/app/references/advanced-installation.md#Binary-cache). If these configuration options are not set, then Cypress may skip the `postinstall` script execution and Cypress will not run. The pnpm [side effects cache](https://pnpm.io/settings#sideeffectscache) uses and caches the results of (pre/post)install hooks and is not compatible with Cypress' own caching. Disable the pnpm [side effects cache](https://pnpm.io/settings#sideeffectscache), for example using the following command, executed in the root of your Cypress project: ```shell pnpm config set side-effects-cache false --location project ``` [pnpm@10.0.0](https://github.com/pnpm/pnpm/releases/tag/v10.0.0) and above require allowlisting `cypress`. Refer to the [pnpm settings](https://pnpm.io/settings) documentation for additional information. In [pnpm@10.4.0](https://github.com/pnpm/pnpm/releases/tag/v10.4.0) and above, the CLI `add` option [--allow-build](https://pnpm.io/cli/add#--allow-build) can be used, for example: ```shell pnpm --allow-build=cypress add --save-dev cypress ``` ### Browsers Each Cypress release includes the Electron-bundled Chromium [browser](/llm/markdown/app/references/launching-browsers.md#Electron-Browser). The latest 3 major versions of the following browsers are also supported: - [Google Chrome](/llm/markdown/app/references/launching-browsers.md#Chrome-Browsers) - [Microsoft Edge](/llm/markdown/app/references/launching-browsers.md#Edge-Browsers) - [Mozilla Firefox](/llm/markdown/app/references/launching-browsers.md#Firefox-Browsers) (*Firefox >=[141.0](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Releases/141) requires Cypress >=[14.1.0](https://docs.cypress.io/app/references/changelog#14-1-0)*) - [WebKit](https://docs.cypress.io/app/references/launching-browsers#WebKit-Experimental) 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 during `cypress run` or abruptly closing ("crashing") - Frozen or missing frames in the video - Increased runtime ### Linux Prerequisites Install required dependencies. See below under [Docker Prerequisites](#Docker-Prerequisites) for information on [Cypress Docker images](https://github.com/cypress-io/cypress-docker-images). These already include the necessary dependencies. #### Ubuntu/Debian For Ubuntu 22.04 and Debian: ```shell 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: ```shell apt-get install libgtk-3-0t64 libgbm-dev libnotify-dev libnss3 libxss1 libasound2t64 libxtst6 xauth xvfb ``` #### Arch ```shell pacman -S gtk3 alsa-lib xorg-server-xvfb libxss nss libnotify ``` #### Amazon Linux 2023 ```shell dnf install -y xorg-x11-server-Xvfb gtk3-devel nss alsa-lib ``` ### Docker Prerequisites [Cypress Docker images](./continuous-integration/overview.md#Cypress-Docker-variants) are available from [Docker Hub](https://hub.docker.com/u/cypress) and the [Amazon ECR (Elastic Container Registry) Public Gallery](https://gallery.ecr.aws/cypress-io). 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](https://github.com/cypress-io/cypress-docker-images/tree/master/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](#Operating-System) 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. ## 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](/llm/markdown/app/references/advanced-installation.md) reference. You can also find instructions to [uninstall Cypress](/llm/markdown/app/references/advanced-installation.md#Uninstall-Cypress) in this reference documentation. ## Continuous integration Please read our [Continuous Integration](/llm/markdown/app/continuous-integration/overview.md) docs for help installing Cypress in CI. When running in Linux you may need to install some [system dependencies](#Linux-Prerequisites) or you can use our [Docker images](#Docker-Prerequisites) which have everything you need prebuilt. ## Next Steps [Open the app](/llm/markdown/app/get-started/open-the-app.md) and take it for a test drive!