Cypress 02 ๐ฒ Installation โ npm install cypress & First Launch
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 Manager | Command |
|---|---|
| npm | npm install cypress --save-dev |
| Yarn | yarn add cypress --dev |
| pnpm | pnpm add --save-dev cypress |
| Bun | bun add --dev cypress |
System Requirements
| Requirement | Version |
|---|---|
| Node.js | 22.x, 24.x, or >=26.x |
| npm | >=10.1.0 |
| Yarn Classic | >=1.22.22 |
| pnpm | >=8.x |
| Windows | 10/11, Server 2019/2022/2025 |
| macOS | Supported versions |
| Linux | Supported distributions |
First Launch Flow
| Step | What Happens |
|---|---|
npx cypress open | Launchpad opens |
| Testing type | E2E or Component |
| Config generation | cypress.config.js, support files, fixtures |
| Browser selection | Chrome, Electron, Firefox |
| Subsequent runs | Skip setup, land on spec list |
Postinstall Fixes
| Manager | Fix |
|---|---|
| npm | npm install-scripts approve cypress + npm rebuild cypress |
| pnpm | pnpm --allow-build=cypress add --save-dev cypress |
| Any | npx 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
| Pitfall | Why It Happens | Fix |
|---|---|---|
cypress open fails after install | postinstall blocked | npx cypress install |
| Node version error | Older than 22.x | Upgrade Node |
| Yarn CLI commands fail | Script named cypress | Rename to cy:open |
| Binary not cached in CI | CYPRESS_CACHE_FOLDER not set | Set the env var to a persisted directory |
| Launchpad does not appear | Running outside project root | Run 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
| Item | Value |
|---|---|
| Install | npm install cypress --save-dev |
| Node requirement | 22.x, 24.x, or >=26.x |
| Binary download | postinstall script |
| Blocked script fix | npx cypress install |
| First launch | npx cypress open |
| Launchpad | Testing 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
postinstallscript fetches the Electron binary into a global cache. If the package manager blocks the script, the install succeeds but Cypress cannot run . - The
postinstallblocking is the most common installation failure. npm 12.0.0+ and pnpm 10.0.0+ block lifecycle scripts by default. The fixes arenpx cypress install,npm install-scripts approve cypress, orpnpm --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. Usecy:openorcy:run. - The cache is worth persisting in CI.
CYPRESS_CACHE_FOLDERpoints 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.
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!