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

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

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.

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.

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

npx cypress verify

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

npx cypress open

Yarn and pnpm users can substitute their respective execution commands:

# 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 with the following content:

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

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 that executes 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 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 triggers 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}