Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
If Cypress will not load after npm install, first separate the npm package from the Cypress application binary. The package can install successfully while its platform-specific binary fails to download, is blocked by a lifecycle-script policy, is missing from the cache, or cannot launch on the operating system. Capture the complete error, operating system, package manager, Cypress version and CI environment before changing configuration.
The fastest diagnosis is to disable the automatic download temporarily, run Cypress’s installer explicitly with CLI debugging enabled, and then follow the branch shown by the resulting error.
Understand what “Cypress won’t load” means
Cypress consists of two installation artifacts:
- The
cypressnpm package in your project dependencies. - A platform-specific Cypress desktop binary downloaded by the package’s
postinstalllifecycle step and stored in a global cache outsidenode_modules.
That is why a successful package-manager install does not prove that the application was downloaded, verified or can launch. Cypress documentation describes the npm module as a normal project dependency, while the binary is managed separately by the Cypress CLI.
Recommended Free Tools
Classify the failure before fixing it
| Symptom | Likely phase | What to inspect |
|---|---|---|
| Install hangs or reports a download, checksum or HTTP error | Postinstall/download | Installer logs, proxy, TLS and firewall access |
cypress run or cypress verify says the binary is missing |
Cache or skipped install | Global cache path and lifecycle-script output |
| Extraction or verification fails | Downloaded archive or permissions | Archive integrity, disk space and cache permissions |
| Verification passes but the app will not open | Operating-system launch | Exact OS error and Linux shared libraries |
Do not assume every loading error is a network failure. A blocked script, an invalid CI cache or a missing Linux library produces a different remedy.
Make the automatic download visible
- Record the exact command and full error output. Include
node --version, Cypress version, OS, package manager and whether the command runs locally or in CI. - Install the npm package without downloading its binary:
npm install --save-dev cypressSet CYPRESS_INSTALL_BINARY=0 for the installation command when you need to guarantee that the automatic binary step is skipped:
CYPRESS_INSTALL_BINARY=0 npm install --save-dev cypress- Run the binary installer directly with CLI diagnostics:
DEBUG=cypress:cli* npx cypress installOn Windows PowerShell, use:
$env:DEBUG="cypress:cli*"; npx cypress installYarn, pnpm and Bun can execute the equivalent installer:
DEBUG=cypress:cli* yarn cypress install
DEBUG=cypress:cli* pnpm cypress install
DEBUG=cypress:cli* bunx cypress installThe resulting log normally identifies whether the problem is script suppression, URL resolution, proxy/TLS access, archive extraction or cache permissions.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsFix a skipped or blocked lifecycle script
Package managers increasingly protect users from dependency lifecycle scripts. If the install output says that scripts were ignored, Cypress’s postinstall step never ran, so no binary was fetched.
Use the package manager’s supported approval flow
Permit or approve the Cypress dependency script according to your package manager’s current security settings, then run the explicit installer again. In CI, prefer a deliberate install stage rather than relying on a background postinstall. Some CI setups require scripts to run in the foreground; others intentionally ignore scripts and therefore need an explicit cypress install command.
Do not globally disable all package-manager protections as a first response. Approving only the required Cypress step limits the trust scope and leaves unrelated dependency scripts protected.
Repair proxy and certificate problems
The binary download occurs during installation, which can use different network settings from your test runtime. Set the proxy for the installer itself:
HTTPS_PROXY=http://proxy.example:8080
HTTP_PROXY=http://proxy.example:8080
DEBUG=cypress:cli* npx cypress installFor an enterprise certificate authority, configure npm’s cafile or ca setting, then repeat the install. NODE_EXTRA_CA_CERTS affects Node.js runtime certificate handling; by itself it does not repair Cypress’s install-time downloader. A proxy that works when tests execute can still fail during the earlier binary download if the installer did not inherit the same variables or npm CA configuration.
Allow the correct Cypress hosts
Firewalls and allowlists must permit all services involved in installation:
download.cypress.ioresolves the version and platform download.cdn.cypress.ioserves the binary archive.registry.npmjs.orgserves the npm package.
Ask your network administrator to allow these hosts over HTTPS, including from the CI runner rather than only from a developer workstation. A successful npm package download does not prove that the CDN is reachable.
Use a mirror, URL or local archive in restricted networks
When public downloads are prohibited, Cypress supports selecting a trusted binary with CYPRESS_INSTALL_BINARY. It can point to a compatible version, a URL or a local ZIP file:
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →CYPRESS_INSTALL_BINARY=/opt/artifacts/cypress.zip npx cypress installFor an internal artifact service, configure CYPRESS_DOWNLOAD_MIRROR when your mirror follows Cypress’s official URL layout. Use CYPRESS_DOWNLOAD_PATH_TEMPLATE when the internal layout is different. Preserve the Cypress version, operating-system platform and architecture expected by the project; a reachable but incompatible archive will fail later during verification or launch.
| Approach | Use it when | Trade-off |
|---|---|---|
| Allow official resolver, CDN and registry | Outbound HTTPS is permitted | Least internal maintenance; depends on external access |
| Full mirror with official layout | You want internal hosting with standard Cypress paths | Mirror must retain the expected version/platform structure |
| Custom path template | Your artifact repository uses its own URL layout | More configuration and version-management responsibility |
| URL or local ZIP | Air-gapped or manually promoted releases | You must distribute the right archive for every runner platform |
Check and restore the binary cache
Cypress stores downloaded binaries in a global cache, not the package manager’s dependency cache. The machine that runs cypress run must have that cache available. In CI, restoring node_modules without restoring the Cypress binary cache commonly produces a missing-binary error.
Relocate the cache deliberately
CYPRESS_CACHE_FOLDER changes the Cypress binary cache location:
export CYPRESS_CACHE_FOLDER="$HOME/.cache/cypress"
npx cypress verifyConfigure the same path for installation and test jobs, ensure it exists at runtime, and cache that directory using your CI provider’s cache mechanism. This variable does not relocate npm, Yarn or pnpm’s own package cache.
Clear a corrupted cache
If logs show extraction, checksum or verification corruption, Cypress troubleshooting recommends clearing the Cypress cache contents and reinstalling. Clearing removes every cached Cypress version, so the next install downloads fresh archives:
npx cypress cache clear
DEBUG=cypress:cli* npx cypress install
npx cypress verifyUse this only after preserving any cache path information needed by your CI configuration.
When downloading succeeds but Cypress still will not launch
Run verification and read the complete operating-system error:
npx cypress verify
npx cypress versionIf verification succeeds but launch fails, stop changing download variables and investigate the OS branch.
Linux shared libraries
When the error names a missing shared library, inspect the Cypress executable with ldd and install the missing system dependency through your distribution’s supported package channel. The exact packages vary by distribution and desktop environment; do not copy a package list intended for a different image.
Permissions and custom locations
Ensure the user running Cypress can read and execute the cached binary and write temporary files. CYPRESS_SKIP_VERIFY=true is not a general loading fix. Cypress documents it for a narrow verification-permission scenario involving a custom binary location; skipping verification can hide a genuinely unusable installation.
CI installation patterns that remain reliable
- Install JavaScript dependencies with the lockfile and record the package-manager version.
- Run
DEBUG=cypress:cli* npx cypress installas an explicit, foreground step. - Cache the directory reported by Cypress for its binary cache, or set
CYPRESS_CACHE_FOLDERto a stable workspace path. - Run
npx cypress verifyon the same image and user that will execute tests. - On cache misses, allow a fresh download instead of treating a missing cache as a test failure caused by application code.
For offline runners, promote a tested ZIP or mirror artifact for each required Cypress version and platform, then set CYPRESS_INSTALL_BINARY or the mirror variables during the install stage.
Or skip the browser setup
If your goal is simply to obtain a clean website image rather than run Cypress browser tests, ScreenshotNeo provides a screenshot API and MCP server. One request handles the browser setup, and it removes cookie-consent banners, newsletter popups and chat widgets before capture. Bot checks, blank pages, failed loads and timeouts are not billed, and response headers identify the page verdict and billing result. AI agents can call its MCP tools, including take_screenshot, get_page_info and capture_pdf.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallcURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);See the ScreenshotNeo documentation for capture options. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Troubleshooting checklist
- Postinstall skipped: approve the Cypress script or run the explicit installer.
- HTTP 403, timeout or DNS error: test resolver, CDN and npm registry access from the installing machine; then apply the required proxy.
- Certificate or self-signed error: configure npm
cafileorca; do not rely onNODE_EXTRA_CA_CERTSalone. - Binary missing in CI: restore the Cypress global cache on the test runner or run installation there.
- Checksum or extraction failure: clear the Cypress cache and download again from a trusted source.
- Verification passes, launch fails: inspect permissions, OS dependencies and the exact platform error, especially Linux shared libraries.
Frequently Asked Questions
Does reinstalling node_modules always fix a Cypress loading error?
No. The Cypress application binary lives in a separate global cache, so reinstalling project dependencies can leave the underlying missing or corrupted binary untouched.
Can I use NODE_EXTRA_CA_CERTS to fix the Cypress download?
Not by itself. Configure the install-time npm cafile or ca setting and pass the required proxy variables to the Cypress installer.
Why does Cypress work locally but fail in CI?
The CI runner may not have the global Cypress cache, may ignore lifecycle scripts, or may have different firewall, proxy, certificate or operating-system dependencies.
The Bottom Line
Run the standalone Cypress installer with DEBUG=cypress:cli*, then fix the specific branch: lifecycle scripts, proxy and npm CA settings, firewall hosts, mirror configuration, cache persistence or OS launch dependencies. The package and binary are separate, so verify both on the machine that runs Cypress.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
