# How to Install Cypress: Complete Guide for npm, yarn, and pnpm

> Learn how to install Cypress effortlessly using npm, yarn, or pnpm. Get the latest Cypress version and start writing end-to-end tests quickly with our simple installation guide.

- Repository: [Cypress.io/cypress](https://github.com/cypress-io/cypress)
- Tags: getting-started
- Published: 2026-06-16

---

**Install Cypress as a development dependency using `npm install cypress --save-dev`, `yarn add cypress --dev`, or `pnpm add cypress --save-dev`, and the platform-specific binary downloads automatically via the postinstall script when you first run the tool.**

Cypress is distributed as a standard npm package through the `cypress-io/cypress` repository. Understanding how to install Cypress requires only a single terminal command, after which the framework handles fetching the Electron-based binary required to execute end-to-end tests in your local environment.

## Prerequisites

Before installing Cypress, ensure your environment meets the following requirements defined in the source code:

- **Node.js** version ≥ 22.19.0 (declared in [`package.json`](https://github.com/cypress-io/cypress/blob/main/package.json) → `engines`)
- **Package manager** — npm, Yarn 1 (≥ 1.22.22), or pnpm
- **Optional binary-only workflow** — For CI environments, you can run `npx cypress install` after the npm install to trigger the binary download logic without pulling the full source tree

## Installation Methods

Cypress supports all major JavaScript package managers. Choose the command that matches your project workflow.

### Installing with npm

The most common installation method uses npm. This command adds Cypress to your `devDependencies` and triggers the automatic binary download.

```bash
npm install cypress --save-dev

```

### Installing with yarn

For Yarn 1 users (the default manager used in the cypress-io/cypress repository), use the `--dev` flag to place Cypress in development dependencies.

```bash
yarn add cypress --dev

```

### Installing with pnpm

pnpm users can install Cypress using the symlink-based store. The `--save-dev` flag ensures proper placement in `devDependencies`.

```bash
pnpm add cypress --save-dev

```

## How the Binary Download Works

The npm package itself is lightweight because it does not include the Electron binary. Instead, the binary download is handled by the `postinstall` script defined in the monorepo’s top-level [`package.json`](https://github.com/cypress-io/cypress/blob/main/package.json) at lines 45-50.

According to the source code, the `"postinstall": "node ./scripts/run-postInstall.js"` entry triggers after the npm install completes. The script at [`scripts/run-postInstall.js`](https://github.com/cypress-io/cypress/blob/main/scripts/run-postInstall.js) checks whether a binary already exists for the current platform; if not, it pulls the matching version from Cypress’s CDN. This design keeps the npm package small while ensuring each developer receives the correct `@packages/electron` binary for their operating system automatically.

## Verifying Your Installation

After installation, confirm that Cypress downloaded the binary correctly and is ready to run.

```bash
npx cypress verify

```

To launch the interactive Test Runner (powered by the downloaded Electron binary), execute:

```bash
npx cypress open

```

Yarn and pnpm users can substitute their respective execution commands:

```bash

# Yarn

yarn cypress verify
yarn cypress open

# pnpm

pnpm exec cypress verify
pnpm exec cypress open

```

## Running Your First Test

Once installed, create a sample test file to verify the setup works end-to-end.

Create [`cypress/e2e/spec.cy.js`](https://github.com/cypress-io/cypress/blob/main/cypress/e2e/spec.cy.js) with the following content:

```javascript
// cypress/e2e/spec.cy.js
describe('My first test', () => {
  it('Visits the Cypress docs', () => {
    cy.visit('https://docs.cypress.io')
    cy.contains('Getting Started')
  })
})

```

Run the test headlessly using:

```bash
npx cypress run

```

This command executes the test against the downloaded binary without opening the GUI, as implemented in the `packages/electron` module.

## Summary

- **Install via npm** using `npm install cypress --save-dev` (or yarn/pnpm equivalents)
- **Binary automation** occurs via the `postinstall` script in [`package.json`](https://github.com/cypress-io/cypress/blob/main/package.json) that executes [`scripts/run-postInstall.js`](https://github.com/cypress-io/cypress/blob/main/scripts/run-postInstall.js)
- **Node requirement** is ≥ 22.19.0 as specified in the repository engines
- **Verify** installations with `npx cypress verify` before running tests
- **Run tests** using `npx cypress run` for headless execution or `npx cypress open` for the interactive GUI

## Frequently Asked Questions

### What Node.js version is required to install Cypress?

Cypress requires Node.js version 22.19.0 or higher, as declared in the `engines` field of the [`package.json`](https://github.com/cypress-io/cypress/blob/main/package.json) file in the cypress-io/cypress repository. Installing with older versions may result in compatibility warnings or errors during the binary download phase.

### Why does Cypress download a binary after npm install?

The npm package contains only the JavaScript CLI code, not the Electron browser binary. The `postinstall` hook in [`package.json`](https://github.com/cypress-io/cypress/blob/main/package.json) triggers [`scripts/run-postInstall.js`](https://github.com/cypress-io/cypress/blob/main/scripts/run-postInstall.js), which detects your operating system and downloads the appropriate binary from Cypress's CDN. This keeps the initial npm install lightweight while ensuring platform-specific compatibility.

### Can I install Cypress without downloading the binary immediately?

Yes. You can install the npm package without triggering the binary download by setting the environment variable `CYPRESS_INSTALL_BINARY=0` before running the install command. Later, you can manually trigger the binary download using `npx cypress install` when you are ready to run tests, which is useful for CI/CD pipelines that separate dependency installation from test execution.

### How do I verify Cypress installed correctly?

Run `npx cypress verify` in your project root. This command checks that the Electron binary exists in the expected location and matches the version specified in your `node_modules`. If successful, it prints a confirmation message; if the binary is missing, it will prompt you to run `npx cypress install` to fetch it.