--- id: app/get-started/install-cypress title: 'Install using npm, Yarn, pnpm, or Bun' 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: fbc9225067c51c52ee13224e3b702cf8a025ec12 updated_at: '2026-08-14T12:36:26.878Z' --- # Installation What you'll learn * How to install Cypress using npm, Yarn, pnpm, or Bun * 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. * npm * Yarn * pnpm * Bun ``` npm install cypress --save-dev ``` ``` yarn add cypress --dev ``` ``` pnpm add --save-dev cypress ``` ``` bun add --dev cypress ``` 1. **Open Cypress:** This launches the Cypress App so you can choose end-to-end (E2E) or component testing (CT) and start writing tests. * npm * Yarn * pnpm * Bun ``` npx cypress open ``` ``` yarn cypress open ``` ``` pnpm cypress open ``` ``` bunx cypress open ``` 1. **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 >=43 * **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](/llm/markdown/app/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) | | [Bun](https://bun.sh/) | \>=1.2.22 | [Install Bun](https://bun.sh/docs/installation) | Cypress uses a `postinstall` script to download the Cypress binary into the [binary cache](/llm/markdown/app/references/advanced-installation.md#Binary-cache). As a security hardening measure, package managers increasingly block dependency lifecycle scripts such as `postinstall` by default. When the script is blocked, the Cypress binary is not downloaded and Cypress will not run. The sections below describe how to allow Cypress to run its `postinstall` script, or how to install the Cypress binary explicitly, for each supported package manager. #### npm configuration Starting in npm 11.16.0, a warning is issued, then starting in npm 12.0.0, npm blocks `postinstall` lifecycle scripts by default. To allow Cypress to run its `postinstall` script, use one of the following approaches. After installing Cypress, you can use the `npm install-scripts` CLI command to add `cypress` to the `allowScripts` list so npm runs the `postinstall` script on install. Use the `--no-allow-scripts-pin` option if you want to allow also future versions of Cypress, or omit if not. `npm rebuild` re-runs the installation to install the Cypress binary after its installation has been allowed. ``` npm install cypress --save-devnpm install-scripts approve cypress --no-allow-scripts-pinnpm rebuild cypress ``` In npm v11 >=11.16.0 warnings are issued. Check the warning prompt for the recommended CLI command. For all npm versions >=11.16.0 you can add `cypress` to `allowScripts` in `package.json` manually instead of using a CLI command: package.json ``` { "allowScripts": { "cypress": true }} ``` Alternatively, if you'd rather not modify your `allowScripts` list, install the Cypress binary explicitly after install completes: ``` npx cypress install ``` #### Yarn configuration [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). Starting in Yarn Modern version 4.14.0, the [enableScripts](https://yarnpkg.com/configuration/yarnrc#enableScripts) configuration option is set to `false` by default, which blocks dependency lifecycle scripts. To allow Cypress to run its `postinstall` script, set `enableScripts` to `true` and add `cypress` to the [npmPreapprovedPackages](https://yarnpkg.com/configuration/yarnrc#npmPreapprovedPackages) list (available in Yarn Modern >=4.10.0) in your project's `.yarnrc.yml` file: .yarnrc.yml ``` enableScripts: truenpmPreapprovedPackages: - cypress ``` `enableScripts` can also be set using the CLI: ``` yarn config set enableScripts true ``` Setting the list of `npmPreapprovedPackages` is less convenient via the CLI and is easier done by editing `.yarnrc.yml` directly. #### pnpm configuration 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: ``` 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: ``` pnpm --allow-build=cypress add --save-dev cypress ``` #### Bun configuration Cypress is detected automatically from a `bun.lock` (text, Bun >=1.2) or `bun.lockb` (binary) lockfile. When you install Cypress with `bun add`, Bun trusts the package and runs its `postinstall` script. When restoring dependencies from an existing manifest with `bun install` (for example in CI), Bun does not run `postinstall` scripts for packages that aren't in its [trustedDependencies](https://bun.sh/docs/install/lifecycle) allowlist. To install the Cypress binary, use one of the following approaches: **Recommended:** Skip lifecycle scripts and install the binary explicitly. This avoids running `postinstall` scripts from dependencies and is the more secure approach: ``` bun install --ignore-scriptsbunx cypress install ``` Alternatively, trust Cypress so Bun runs the `postinstall` script on install. You can use the CLI: ``` bun pm trust cypress ``` Or add `cypress` to `trustedDependencies` in `package.json` manually: package.json ``` { "trustedDependencies": ["cypress"]} ``` Refer to [Advanced Installation](/llm/markdown/app/references/advanced-installation.md#Troubleshoot-installation) for additional Bun installation options. ### 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: ``` 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](/llm/markdown/app/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!