Cypress CYPRESS_INSTALL_BINARY mirror / offline install in CI

By Kaveh Alemi·Latchkey

CYPRESS_INSTALL_BINARY tells Cypress where to fetch its binary: a mirror URL, a local .zip, or 0 to skip. When it points at the wrong version or an unreachable path, the install fails or the binary does not match the cypress npm package.

What this error means

The install fails to fetch the binary, or a run reports a version mismatch between the installed cypress package and the binary the variable pointed at.

The Cypress binary version 12.17.4 does not match the expected package version 13.9.0
CYPRESS_INSTALL_BINARY=https://mirror.internal/cypress/12.17.4.zip
Please reinstall Cypress so the binary matches the package.

Common causes

The mirror URL points at a stale version

The .zip on the mirror is an older Cypress build than the cypress package installed by npm, so the versions disagree.

The mirror or local file path is unreachable

A wrong host, missing auth, or a moved zip makes the fetch fail entirely.

How to fix it

Match the binary URL to the package version

1. Read the cypress version from package-lock.json.
2. Update CYPRESS_INSTALL_BINARY to the matching zip on the mirror.
3. Reinstall so the binary and package versions align.

env:
  CYPRESS_INSTALL_BINARY: https://mirror.internal.example.com/cypress/13.9.0.zip

Skip the download only if you provide the binary

Set the variable to 0 to skip the fetch, but then supply a preinstalled or cached binary path.

env:
  CYPRESS_INSTALL_BINARY: '0'

How to prevent it

• Keep the mirror zip version in lockstep with the cypress package.
• Only skip the download when a cached or preinstalled binary is guaranteed.
• Cache the Cypress folder so mirror flakiness is not on the critical path.

Frequently asked questions

Related guides

References

• GitHub Actions documentation