Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Cypress says the npm package is installed but the binary is missing

ErrorThe cypress npm package is installed, but the Cypress binary is missing.

Short answer

The npm package is only a launcher. The Cypress binary is downloaded by an install script into a cache folder. It goes missing when install scripts are skipped, when the download was turned off, or when the cache folder differs between install and run. Print the cache path and reinstall the binary.

  • Applies to Cypress 15, Node.js 22, npm 10, Linux CI and Docker
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask Cypress where it looks for the binary and which versions are there. Do this in the same job and user that runs the tests.

    npx cypress cache path
    npx cypress cache list
  2. 2Match what you see, then jump to its fix

    1. 1The install used --ignore-scripts, or npm is configured with ignore-scripts=trueInstall scripts were skipped, so nothing downloaded the binaryFix
    2. 2The variable exists in the CI settings, Dockerfile or imageCYPRESS_INSTALL_BINARY=0 is set in the environmentFix
    3. 3Install works, but a later stage, user or container looks in a different folderThe binary cache folder differs between install and testFix

What does the error look like?

  • The cypress npm package is installed, but the Cypress binary is missing.
  • Cypress binary is missing after npm install in CI or in a Docker build

Cause 1 of 3

Install scripts were skipped, so nothing downloaded the binary

1Check

Cypress downloads its binary from a postinstall hook. If the hook is skipped for any reason, the binary is missing unless it was already cached. npm does not run package scripts when ignore-scripts is true.

npm config get ignore-scripts

2Fix

Install the binary explicitly after the dependency install.

npm ci --ignore-scripts
npx cypress install

3Verify

The version is listed, and the binary starts.

npx cypress cache list
npx cypress verify

Confirmed by docs.cypress.io

Did this fix it?

Cause 2 of 3

CYPRESS_INSTALL_BINARY=0 is set in the environment

1Check

A value of 0 tells the install step to skip the binary download entirely.

env | grep CYPRESS

2Fix

Unset it for the install, or install the binary yourself after the packages.

unset CYPRESS_INSTALL_BINARY
npm ci

3Verify

The cache list shows the version.

npx cypress cache list

Confirmed by docs.cypress.io

Did this fix it?

Cause 3 of 3

The binary cache folder differs between install and test

1Check

On Linux the default cache is ~/.cache/Cypress, and CYPRESS_CACHE_FOLDER has to exist every time you launch Cypress. A multi-stage Docker build, a different user, or a CI cache that restored an older folder gives a different result.

echo "$HOME $CYPRESS_CACHE_FOLDER"
npx cypress cache path

2Fix

Point both stages at one folder, and make CI cache that folder with a key that includes the lock file.

export CYPRESS_CACHE_FOLDER=/opt/cypress-cache
npx cypress install

3Verify

The path is the same in every stage, and verify passes there.

npx cypress cache path
npx cypress verify

Confirmed by docs.cypress.io

Did this fix it?

How do I stop it coming back?

  • Run npx cypress cache path in CI so the log always shows where the binary should be.
  • Cache the Cypress binary folder, but do not cache node_modules across builds.
  • Use an official cypress/included image if you want the binary baked into the image.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.