Implementation:Cypress io Cypress Install Start

Knowledge Sources	Cypress Cypress Install
Domains	CLI, Package_Management
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for downloading and caching the Cypress binary during npm package installation provided by the Cypress CLI.

Description

The install.start function orchestrates the entire binary installation process. It checks environment variables for version overrides, determines whether the binary is already cached, downloads it from the CDN if needed, unzips it, and verifies the installation. It uses listr2 for progress reporting and fs-extra for filesystem operations.

Usage

This function is invoked automatically via the npm postinstall script when npm install cypress is run. It can also be triggered manually via cypress install CLI command or programmatically for CI cache warming.

Code Reference

Source Location

• Repository: cypress-io/cypress
• File: cli/lib/tasks/install.ts
• Lines: L195-369

Signature

const start = async (options: any = {}): Promise<any> => {
  // options.force: boolean - force reinstall even if cached
  // options.buildInfo: object - version metadata for build identification
  // Checks CYPRESS_INSTALL_BINARY env var
  // Checks CYPRESS_CACHE_FOLDER env var for custom cache location
  // Downloads from CDN via downloadAndUnzip({ version, installDir, downloadDir })
  // Verifies via state.getBinaryPkgAsync()
}

Import

// Internal module - invoked via CLI postinstall script
// cli/package.json: "postinstall": "patch-package && tsx ./scripts/post-install.ts"
import { start } from './tasks/install'

I/O Contract

Inputs

Name	Type	Required	Description
options	object	No	Installation options
options.force	boolean	No	Force reinstall even if binary is cached
options.buildInfo	object	No	Version metadata for build identification
CYPRESS_INSTALL_BINARY	env var	No	Custom binary version or URL ("0" to skip)
CYPRESS_CACHE_FOLDER	env var	No	Custom cache directory path

Outputs

Name	Type	Description
Binary files	Files	Cypress binary installed to ~/.cache/Cypress/<version>/
Verification	Promise<any>	Resolves when installation is complete and verified

Usage Examples

Automatic Installation (via npm)

# Standard installation - triggers postinstall automatically
npm install cypress

# Force reinstall
CYPRESS_INSTALL_BINARY=force npx cypress install --force

# Custom cache folder (CI)
CYPRESS_CACHE_FOLDER=/ci/cache/cypress npm install cypress

# Skip binary download
CYPRESS_INSTALL_BINARY=0 npm install cypress

Programmatic Usage

const install = require('./tasks/install')

// Install with default options
await install.start()

// Force reinstall
await install.start({ force: true })

Related Pages

Implements Principle

• Principle:Cypress_io_Cypress_Binary_Installation

Requires Environment

• Environment:Cypress_io_Cypress_Node_Runtime_Environment
• Environment:Cypress_io_Cypress_Linux_Display_Server

Uses Heuristic

• Heuristic:Cypress_io_Cypress_Global_Install_Warning