How to Cache and Install the Cypress Binary in CI

Cypress installs an npm package and, separately, a large platform binary. Caching only node_modules loses the binary and re-downloads it every run.

The Cypress binary lives in ~/.cache/Cypress, not node_modules. Treating it as a distinct cache is the key to fast, reliable Cypress installs in CI.

Why it fails in CI

The binary download from the Cypress CDN times out or is rate-limited.
Only node_modules was cached, so the binary re-downloads each run.
A version bump leaves a cached binary that no longer matches the package.

Install it reliably

Install the package, cache the binary directory keyed on the Cypress version, and verify the binary before running tests. Pin the version for cache stability.

Terminal

npm ci                 # installs the cypress package
npx cypress install    # ensures the binary is present
npx cypress verify     # validates it before tests

# point the cache elsewhere if needed:
export CYPRESS_CACHE_FOLDER="$PWD/.cache/Cypress"

Cache & speed

Cache ~/.cache/Cypress keyed on the lockfile (which pins the version). The download is a known flaky step; auto-retry of transient failures and larger managed runners reduce lost time.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.cache/Cypress
    key: cypress-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}

Common errors

The Cypress App could not be downloaded → transient CDN issue; retry or mirror the binary.
Cypress verification timed out → restore the binary cache or raise CYPRESS_VERIFY_TIMEOUT.
Re-downloads every run → you cached node_modules but not ~/.cache/Cypress.

Key takeaways

The Cypress binary lives in ~/.cache/Cypress, separate from node_modules.
Cache that directory keyed on the pinned version.
Run cypress verify to catch a bad binary before the suite.