Principle:Cypress io Cypress Binary Installation
| Knowledge Sources | |
|---|---|
| Domains | CLI, Package_Management |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
A mechanism for downloading, caching, and verifying platform-specific test runner binaries during package installation.
Description
Binary installation addresses the challenge of distributing native Electron applications through npm. When a user runs npm install cypress, the CLI package is installed via npm, but the actual test runner binary (an Electron application) must be downloaded separately from a CDN and cached locally. This two-phase approach separates the lightweight CLI shim from the heavy binary, enabling caching across projects and CI runs.
The installation process verifies binary integrity, handles version pinning, supports custom cache directories via CYPRESS_CACHE_FOLDER, and provides force-reinstall capabilities. On CI, binary caching dramatically reduces installation time.
Usage
Use this principle when setting up Cypress in a new project or CI environment. It applies whenever npm install cypress or yarn add cypress is executed and the binary needs to be downloaded or restored from cache.
Theoretical Basis
The binary installation follows a multi-step verification pipeline:
1. Check CYPRESS_INSTALL_BINARY env var (skip if "0", use custom URL if set)
2. Determine version to install (from package.json or override)
3. Check if binary already cached at ~/.cache/Cypress/<version>/
4. If cached and valid → skip download
5. If not cached → download from CDN, unzip, verify with state.getBinaryPkgAsync()
6. Set binary as executable
This approach ensures idempotent installations and supports offline environments through pre-populated caches.