skip to content

What does CYPRESS_INSTALL_BINARY control, and what does setting it to 0 do?

level: middleimportance: should knowfreq 44%

answer

  1. Two install steps, not one
  2. The variable touches only the second step
  3. Accepts a version, a URL, a file
  4. Zero means fetch nothing
  5. Nothing records the choice for next time

basics

~10 s

CYPRESS_INSTALL_BINARY chooses which Cypress binary the postinstall step downloads: a version, a URL, or a local zip file. Setting it to 0 skips the binary download entirely, leaving only the small npm module installed.

solid answer

~40 s

Installing Cypress is two steps: the small `cypress` npm module, then a large platform-specific binary that a `postinstall` script downloads into a global cache. `CYPRESS_INSTALL_BINARY` controls only that second step. Give it a version to pin a binary different from the package, an `https://` URL to pull from an internal host when the public download server is blocked, or a path to a local `.zip` to install offline. Setting it to `0` skips the download completely, which is how you build a runner image whose binary arrives in a separate step, or make a failing install debuggable by running `cypress install` on its own afterwards. The choice is not recorded anywhere, so every later install must set it again or it silently reverts to the default binary.

code

bash · 4 lines
bash
cd packages/storefront-web
CYPRESS_INSTALL_BINARY=0 npm ci
DEBUG=cypress:cli* npx cypress install
npx cypress verify

go deeper

for a junior

Recall that Cypress installs in two parts and that this variable governs the download of the second one. Knowing that 0 means no download is the point to hold on to.

for a middle

Be ready to list the values it accepts and explain the postinstall model that makes them meaningful, including why the choice has to be repeated on every install.

for a senior

An interviewer expects the operational consequences: silent reversion to the default binary, the binary-versus-package mismatch warning, and when a committed .npmrc setting beats an environment variable on an agent.

for a principal

Own the supply chain: whether binaries come from a public host, an internal mirror or a checked-in artefact, who approves that source, and how a version pin is enforced across many repositories.

## The install model the variable plugs into Installing Cypress is two steps, not one. `npm install cypress` adds a **small npm module** — the CLI, the TypeScript types and a launcher. The **Cypress application** is a large, platform-specific binary that a `postinstall` script downloads afterwards and stores in a global cache outside `node_modules`, so one download can serve every project on the machine. When you later launch Cypress, the npm module looks up the matching binary in that cache. `CYPRESS_INSTALL_BINARY` is the switch on the second step only. It never changes which npm module version is installed — that still comes from your dependency file — it changes **which binary the postinstall step fetches, or whether it fetches one at all**. ## The four things you can give it | Value | Effect | | --- | --- | | a version, e.g. `15.16.0` | download that binary version instead of the one matching the package | | an `https://…` URL | download the binary from that address, for networks that cannot reach the public download host | | a path to a local `.zip` | install from a file already on disk, with no network at all | | `0` | **skip the binary download entirely** | The `0` case is the one that matters for prebuilt run images and for debugging: 1. **Building a runner image.** Install the npm module in one step and add the binary in a later, separately cacheable step, instead of doing both inside one opaque install. 2. **Making a failing install readable.** Package managers run `postinstall` in the background, so a download or unzip failure produces almost no output. Skipping it and then running `cypress install` on its own, with the CLI's debug logging enabled, shows exactly where it broke. 3. **A job that never needs the binary.** A lint or type-check job in a storefront monorepo that only needs the `cypress` types has no reason to pull hundreds of megabytes. ## The trap: it is not remembered The fact that a binary was installed from a custom version, URL or file is **not recorded in your dependency file**. Every later install has to set the same variable again, or it will quietly fetch the default binary instead. Three consequences follow: - Set it in your shell for one install and a colleague — or the next pipeline job — gets something different. - If you skip the download with `0` and never run `cypress install` afterwards, the launch fails because no binary matches the package. - If the binary that ends up in the cache does not match the package version, Cypress prints a warning that the binary version does not match the expected package version and that the two may not work properly together. It is a warning, not an error — so it scrolls past in a pipeline log unless someone is looking for it. ## Making the setting travel with the repo Because a shell export does not survive a move to another machine or agent, every `CYPRESS_*` install variable can also be committed. Cypress resolves each one in this order, taking the first value it finds: 1. the real environment variable, e.g. `CYPRESS_INSTALL_BINARY`; 2. `npm_config_<name>`, set through `.npmrc` or `npm config`; 3. the lowercase `npm_config_<name>`; 4. `npm_package_config_<name>`, from a `config` block in `package.json`. So `cypress_install_binary=https://internal.example.com/cypress.zip` in an `.npmrc`, or the same key in a `config` block, applies automatically to everyone who installs the repo. That is usually the right home for an internal-mirror setting; a one-off `0` for a single image build is better left on the command line where it is visible. ## Related switches, and where each one bites - `CYPRESS_CACHE_FOLDER` moves **where** the binary is stored, and matters at launch time as well as install time. - `CYPRESS_RUN_BINARY` is the run-time counterpart: it points the npm module at a specific unzipped binary on disk instead of one resolved from the cache. - `cypress install --force` re-downloads and overwrites even when a matching binary is already cached; without it, `cypress install` does nothing when the cache already holds the right version. - `cypress verify` runs a smoke test on the installed binary, and it also runs automatically as part of a launch, so a broken or half-extracted binary surfaces there rather than mid-suite.

  • You set CYPRESS_INSTALL_BINARY=0 in a container and never fetched the binary. What happens at launch?
    The npm module installs fine, but the launch fails because it cannot find a binary matching the package version in the cache. The fix is to run `cypress install` as its own step, or to launch a binary you unzipped elsewhere by pointing `CYPRESS_RUN_BINARY` at it. Nothing about the skipped download is recorded, so the failure only appears when Cypress is actually launched.
  • How do you apply a custom Cypress binary source to everyone in the repo without exporting a shell variable?
    Commit it. Every `CYPRESS_*` install variable can also be set as `cypress_install_binary` in an `.npmrc`, or in a `config` block in `package.json`. Cypress resolves the real environment variable first, then `npm_config_<name>`, then its lowercase form, then `npm_package_config_<name>`, so a committed value gives every machine and every agent the same behaviour automatically.

saying these in an interview costs you the question

  • Thinks the variable changes the installed npm module version
  • Believes the setting is remembered by package.json
  • Says 0 disables Cypress rather than the download
  • Confuses it with the run-time CYPRESS_RUN_BINARY variable
  • Assumes a mismatched binary version fails loudly