Environment:Cypress io Cypress Node Runtime Environment

Knowledge Sources	Cypress CONTRIBUTING.md
Domains	Infrastructure, Testing
Last Updated	2026-02-12 01:00 GMT

Overview

Cross-platform Node.js runtime environment with Yarn Classic package manager for running and developing the Cypress test framework.

Description

This environment defines the Node.js runtime, package manager, and native build toolchain required to install, run, and develop Cypress. The published cypress npm package supports Node.js 20.x, 22.x, and 24.x+. Contributing to the Cypress monorepo requires the exact Node.js version pinned in the root .node-version file (currently 22.19.0), Yarn v1 Classic (>=1.22.22), and Python (for node-gyp native module compilation).

Usage

Use this environment for any interaction with Cypress: installing the npm package, running E2E or component tests, developing the Cypress app from source, or building the Cypress binary. The Node.js version constraint is the first prerequisite checked by the CLI and enforced by the engines field in package.json.

System Requirements

Category	Requirement	Notes
OS	Windows (x64, arm64), macOS (x64, arm64), Linux (x64, arm64)	Validated by `install.ts:validateOS()`
Node.js (user)	^20.1.0 OR ^22.0.0 OR >=24.0.0	From cli/package.json engines field
Node.js (contributor)	22.19.0 (exact)	From .node-version; enforced by scripts/check-node-version.js
Package Manager	Yarn v1 Classic >= 1.22.22	Corepack compatible but not required
Disk	~500MB for binary cache	Downloaded zip + extracted Electron binary

Dependencies

System Packages

`build-essential` (Debian/Ubuntu) — required for node-gyp native module compilation
`python` 3.9 - 3.14 — required by node-gyp
Visual Studio 2022 Build Tools with "Desktop development with C++" (Windows)

Node.js Packages

`cypress` >= 15.10.0 (published package)
`electron` = 37.6.0 (bundled in binary)
`yarn` >= 1.22.22 (package manager)
`lerna` = 8.1.9 (monorepo orchestration, dev only)

Credentials

The following environment variables are optionally used:

`CYPRESS_INSTALL_BINARY`: Override the binary download URL or version. Set to `0` to skip binary install.
`CYPRESS_CACHE_FOLDER`: Override the default binary cache directory.
`CYPRESS_RUN_BINARY`: Point to a custom Cypress binary path at runtime.
`CYPRESS_DOWNLOAD_USE_CA`: Use custom CA certificates for binary download.
`CYPRESS_INTERNAL_ENV`: Set the internal environment (staging, development, production).

Quick Install

# Install Cypress as a project dependency
npm install --save-dev cypress

# Or with Yarn
yarn add --dev cypress

# Verify installation
npx cypress verify

Code Evidence

Node.js version constraint from `cli/package.json:111-113`:

"engines": {
  "node": "^20.1.0 || ^22.0.0 || >=24.0.0"
}

Development Node version check from `scripts/check-node-version.js:15-18`:

if (nodeVersionNeeded[0] !== nodeVersion[0]) {
  console.error('🛑 .node-version specified %s', nodeVersionNeededString)
  console.error('but current Node is %s', process.versions.node)
  process.exit(1)
}

Platform validation from `cli/lib/tasks/install.ts:146-149`:

const validateOS = async (): Promise<RegExpMatchArray | null> => {
  const platformInfo = await util.getPlatformInfo()
  return platformInfo.match(/(win32-x64|win32-arm64|linux-x64|linux-arm64|darwin-x64|darwin-arm64)/)
}

Root package.json engines from `package.json:209-212`:

"engines": {
  "node": ">=22.19.0",
  "yarn": ">=1.22.22"
}

Common Errors

Error Message	Cause	Solution
`The engines field in package.json requires node >=22.19.0`	Using wrong Node.js version for development	Install Node.js 22.19.0 using nvm or the version manager of your choice
`invalidOS` error during install	Unsupported platform/architecture combination	Cypress supports win32-x64, win32-arm64, linux-x64, linux-arm64, darwin-x64, darwin-arm64
`CYPRESS_INSTALL_BINARY = 0, skipping install`	Environment variable set to skip binary download	Unset `CYPRESS_INSTALL_BINARY` or set to desired version
`Failed to access cache directory: EACCES`	Insufficient permissions on cache directory	Fix permissions on `~/.cache/Cypress` or set `CYPRESS_CACHE_FOLDER` to a writable directory

Compatibility Notes

Windows arm64: The CLI detects arm64 on Windows but overrides the download to x64 binary (arm64 binary not yet available as a pre-release).
Corepack: The monorepo is Corepack-compatible with a `packageManager` field in root package.json, but Corepack is not required and is considered experimental by Node.js.
Yarn workspace bug: There is a known Yarn bug (yarn#7734) that may cause issues adding new dependencies. Workaround: `npx yarn@1.19.1 workspace @packages/server add my-new-dep`.
Windows path resolution: On Windows, set `yarn config set script-shell "C:\Windows\system32\cmd.exe"` to resolve path issues during development builds.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment