| | |

Cypress 02 ๐ŸŒฒ Installation โ€” npm install cypress & First Launch

โฑ๏ธ Estimated read: 8 min | |

Cypress installs as a dev dependency and downloads its own Electron-based browser binary in a postinstall script. The install itself is one command, but the first launch is where the project gets configured: the Launchpad opens, asks whether the project is doing E2E or component testing, generates the config file and folder structure, and launches a browser. The two steps are separate because the binary download can fail silentlyโ€”package managers are increasingly blocking postinstall scripts, and the result is a Cypress install that looks successful until the first cypress open fails with “binary not found.”

This chapter covers the install command, the system requirements, the postinstall blocking issue that has become the most common installation failure, and the Launchpad flow that configures the project on first launch.

Key point: npm install cypress --save-dev installs the package and triggers a postinstall script that downloads the binary; if the package manager blocks the script, run npx cypress install explicitly, then open the app with npx cypress open to let the Launchpad scaffold the project.


a. The install command and system requirements

Cypress is installed with the standard dev-dependency command. The package manager variants are npm install cypress --save-dev, yarn add cypress --dev, pnpm add --save-dev cypress, and bun add --dev cypress .

npm install cypress --save-dev

The system requirements are specific. Cypress supports Windows 10/11 (x64), Windows Server 2019/2022/2025, macOS, and the supported Linux distributions. The Node.js requirement is Node.js 22.x, 24.x, or >=26.x . A project on an older Node version needs to upgrade before the install will work. The package manager requirements are npm >=10.1.0, Yarn Classic >=1.22.22, Yarn Modern >=4.x, pnpm >=8.x, and Bun >=1.2.22 .

Cypress does not ship the browser as part of the npm package. The package contains the CLI and the test runner code; the binaryโ€”an Electron application that bundles Chromium and the Cypress runnerโ€”is downloaded by the postinstall script into a global cache. The cache locations are ~/Library/Caches/Cypress on macOS, ~/.cache/Cypress on Linux, and %LOCALAPPDATA%/Cypress/Cache on Windows . The CYPRESS_CACHE_FOLDER environment variable relocates the cache, which is the standard CI optimization: point it at a directory the CI provider persists, and the multi-minute download becomes a cache hit.


b. The postinstall blocking problem

The postinstall script is the install step that most often fails silently. Package managers are increasingly blocking dependency lifecycle scripts as a security hardening measure, and when the script is blocked, the Cypress binary is not downloaded and Cypress will not run .

For npm, the blocking starts with npm 11.16.0 (warning) and npm 12.0.0 (blocked by default). The fix is to allow the script for the Cypress package:

# Install Cypress
npm install cypress --save-dev

# Allow the postinstall script
npm install-scripts approve cypress --no-allow-scripts-pin

# Re-run the install to download the binary
npm rebuild cypress

Alternatively, add cypress to the allowScripts field in package.json, or skip the script entirely and download the binary explicitly with npx cypress install .

For pnpm, versions 10.0.0 and above require allowlisting the package. The --allow-build flag on add handles it in one step:

pnpm --allow-build=cypress add --save-dev cypress

The symptom of the blocked script is a successful npm install followed by a cypress open that fails with a message about the binary not being found. The fix is always one of the two above: allow the script, or run npx cypress install manually.


c. The first launch and the Launchpad

npx cypress open (run from the project root) starts the Cypress app. The first launch opens the Launchpad, which walks through the configuration decisions that a new project needs .

The Launchpad asks three questions in order. First, it asks for the testing type: E2E or Component Testing. E2E runs the whole application in a browser and visits pages the way a user would; Component Testing mounts individual components in isolation. The choice is not permanentโ€”the other type can be added laterโ€”and the documentation recommends E2E if the team is unsure .

Second, the Launchpad generates the configuration. It creates cypress.config.js (or .ts), the cypress/support/e2e.js support file, and example fixtures and specs. The files are listed for review before the user continues .

Third, the Launchpad presents the browsers it found on the system and launches the selected one. From that point, the project is configured, and subsequent cypress open runs skip the full setup and land directly on the spec list .

The npm script shortcut is worth adding after the first launch:

{
  "scripts": {
    "cy:open": "cypress open",
    "cy:run": "cypress run"
  }
}

The script name should not be cypress itself, especially with Yarn, because Yarn will reference the script instead of the binary and the Cypress CLI commands will not work as expected. A descriptive name like cy:open or cy:run avoids the collision .


Complete Example Session

# ============================================
# PART 1: CHECK REQUIREMENTS
# ============================================
node --version
# v22.12.0 or newer

# ============================================
# PART 2: INSTALL
# ============================================
npm install cypress --save-dev

# If npm >= 11.16.0 blocks the postinstall script:
npm install-scripts approve cypress --no-allow-scripts-pin
npm rebuild cypress

# Or install the binary explicitly:
npx cypress install

# ============================================
# PART 3: FIRST LAUNCH
# ============================================
npx cypress open

# Launchpad prompts:
# 1. Testing type: E2E Testing
# 2. Review generated config:
#    - cypress.config.js
#    - cypress/support/e2e.js
#    - cypress/fixtures/example.json
#    - cypress/e2e/spec.cy.js
# 3. Choose browser: Chrome / Electron / Firefox

# ============================================
# PART 4: THE NPM SCRIPT
# ============================================
# package.json
# "scripts": {
#   "cy:open": "cypress open",
#   "cy:run": "cypress run"
# }

npm run cy:open

The parts covered the version check, the install and the postinstall workaround, the Launchpad flow, and the npm script shortcut.


Quick Reference

Install Commands

Package ManagerCommand
npmnpm install cypress --save-dev
Yarnyarn add cypress --dev
pnpmpnpm add --save-dev cypress
Bunbun add --dev cypress

System Requirements

RequirementVersion
Node.js22.x, 24.x, or >=26.x
npm>=10.1.0
Yarn Classic>=1.22.22
pnpm>=8.x
Windows10/11, Server 2019/2022/2025
macOSSupported versions
LinuxSupported distributions

First Launch Flow

StepWhat Happens
npx cypress openLaunchpad opens
Testing typeE2E or Component
Config generationcypress.config.js, support files, fixtures
Browser selectionChrome, Electron, Firefox
Subsequent runsSkip setup, land on spec list

Postinstall Fixes

ManagerFix
npmnpm install-scripts approve cypress + npm rebuild cypress
pnpmpnpm --allow-build=cypress add --save-dev cypress
Anynpx cypress install

Best Practices

โœ… Do This:

# Check Node version before installing
node --version                                                # โœ…

# Install as dev dependency
npm install cypress --save-dev                                # โœ…

# Run the binary install explicitly if the script is blocked
npx cypress install                                           # โœ… 

# Add a descriptive npm script
"cy:open": "cypress open"                                     # โœ…

โŒ Don’t Do This:

# Install as production dependency
npm install cypress                                           # โŒ

# Name the script "cypress"
"cypress": "cypress open" # Yarn collision                     # โŒ 

# Assume the binary downloaded if the install succeeded
# (postinstall may be blocked)                                # โŒ

Common Pitfalls

PitfallWhy It HappensFix
cypress open fails after installpostinstall blockednpx cypress install
Node version errorOlder than 22.xUpgrade Node
Yarn CLI commands failScript named cypressRename to cy:open
Binary not cached in CICYPRESS_CACHE_FOLDER not setSet the env var to a persisted directory
Launchpad does not appearRunning outside project rootRun from project root

Real-World Examples

1. Install

npm install cypress --save-dev

2. Postinstall workaround

npx cypress install

3. First launch

npx cypress open

4. npm script

"cy:open": "cypress open"

5. CI cache

export CYPRESS_CACHE_FOLDER=~/.cache/Cypress

6. Check cache

npx cypress cache list

7. Clear cache

npx cypress cache clear

8. Skip Launchpad prompts

npx cypress open --e2e --browser chrome

9. pnpm allowlist

pnpm --allow-build=cypress add --save-dev cypress

10. Verify install

npx cypress verify

Visual

Install and First Launch

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  npm install cypress --save-dev                         โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  postinstall script                                     โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚    โ”Œโ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”                                          โ”‚
โ”‚    โ–ผ         โ–ผ                                          โ”‚
โ”‚  allowed   blocked                                      โ”‚
โ”‚    โ”‚         โ”‚                                          โ”‚
โ”‚    โ–ผ         โ–ผ                                          โ”‚
โ”‚  binary    npx cypress                                  โ”‚
โ”‚  downloaded install                                     โ”‚
โ”‚    โ”‚         โ”‚                                          โ”‚
โ”‚    โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜                                          โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  npx cypress open                                       โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  Launchpad: testing type โ†’ config โ†’ browser             โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

The Launchpad Flow

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  STEP 1: Testing Type                                   โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”           โ”‚
โ”‚  โ”‚ E2E Testing        Component Testing     โ”‚           โ”‚
โ”‚  โ”‚ (whole app)        (isolated components) โ”‚           โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜           โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  STEP 2: Generated Config                               โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”           โ”‚
โ”‚  โ”‚ cypress.config.js                        โ”‚           โ”‚
โ”‚  โ”‚ cypress/support/e2e.js                   โ”‚           โ”‚
โ”‚  โ”‚ cypress/e2e/spec.cy.js                   โ”‚           โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜           โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  STEP 3: Browser Selection                              โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”           โ”‚
โ”‚  โ”‚ Chrome / Electron / Firefox              โ”‚           โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜           โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Postinstall Blocking

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  npm >= 11.16.0: warns                                   โ”‚
โ”‚  npm >= 12.0.0: blocks by default                       โ”‚
โ”‚                                                         โ”‚
โ”‚  Symptom:                                               โ”‚
โ”‚  install succeeds โ†’ cypress open fails (no binary)      โ”‚
โ”‚                                                         โ”‚
โ”‚  Fix:                                                   โ”‚
โ”‚  npm install-scripts approve cypress                    โ”‚
โ”‚  npm rebuild cypress                                    โ”‚
โ”‚  OR                                                     โ”‚
โ”‚  npx cypress install                                    โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Summary

ItemValue
Installnpm install cypress --save-dev
Node requirement22.x, 24.x, or >=26.x
Binary downloadpostinstall script
Blocked script fixnpx cypress install
First launchnpx cypress open
LaunchpadTesting type โ†’ config โ†’ browser
npm script"cy:open": "cypress open"
Cache location~/.cache/Cypress (Linux)

Key takeaways:

  • The install is one command, but the binary is a separate download. The postinstall script fetches the Electron binary into a global cache. If the package manager blocks the script, the install succeeds but Cypress cannot run .
  • The postinstall blocking is the most common installation failure. npm 12.0.0+ and pnpm 10.0.0+ block lifecycle scripts by default. The fixes are npx cypress install, npm install-scripts approve cypress, or pnpm --allow-build=cypress .
  • The first launch is where the project gets configured. The Launchpad asks for the testing type, generates the config and folder structure, and launches a browser. Subsequent launches skip the full setup .
  • The npm script should not be named cypress. Yarn resolves the script before the binary, and the CLI commands break. Use cy:open or cy:run .
  • The cache is worth persisting in CI. CYPRESS_CACHE_FOLDER points at a directory the CI provider caches, turning a multi-minute binary download into a cache hit .

Remember: The Cypress installation is two steps: the package and the binary. The package install is fast; the binary download is the one that fails silently when the package manager blocks the postinstall script. If cypress open says the binary is missing, run npx cypress install and try again. The first launch is the Launchpad, and the choices it asks for are the ones that configure the project. Add the npm script after the first launch, and keep the binary cache in mind for CI.

Was this helpful?


Stop using slow, ad-bloated tool sites! ๐Ÿคฎ

๐Ÿ”Ž Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
โœ… Finance (Mortgage, Interest, Inflation)
โœ… Tech (Base64, JSON, Dev Suite, IP)
โœ… Health (BMI, BMR, TDEE)
โœ… Productivity (Timer, Workspace, QR)

โšก๏ธ Fast & Private
๐Ÿ”’ No data leaves your device
๐Ÿ’Ž 100% Free

๐Ÿ”— Use it now: https://tools.kandz.me
๐Ÿ”– Bookmark itโ€”youโ€™ll need it later!