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 errorsInstall Cypress in your project root with npm install cypress --save-dev, then run npx cypress open to launch the Cypress app and configure end-to-end or component testing. For automated, headless execution, use npx cypress run. If npm installs the package but the Cypress binary is missing, run npx cypress install explicitly and verify it with npx cypress verify.
Check Node.js, npm, and operating-system support first
Cypress depends on both its npm package and a platform-compatible Cypress binary. Before installing, check the current Cypress system requirements for your Node.js and npm versions, operating system, architecture, and any browser or server environment you plan to use. These requirements change over time, so do not rely on an old project’s version list when setting up a new machine.
- The current Cypress guide lists Node.js 22.x, 24.x, or 26.x and later, and npm 10.1.0 or later.
- Listed operating systems include macOS 13.5 or later, Windows 10/11 x64, and supported Linux distributions, including Ubuntu 22.04 or later. Linux arm64 has specific caveats; confirm that your exact distribution and architecture are supported.
- For a project that already exists, run
node --versionandnpm --versionin a terminal to see the versions currently on your PATH. If either does not meet the current Cypress requirements, upgrade it or use a compatible environment before troubleshooting Cypress installation.
Install Cypress in the project
Open a terminal in the project root—the directory containing the project’s package.json—and install Cypress as a development dependency:
npm install cypress --save-devThis adds the Cypress npm module to the project’s development dependencies. Normally, its installation lifecycle also downloads the matching Cypress binary into a global cache on the machine. The npm package and executable binary are related but distinct: seeing the package in package.json does not by itself prove that the binary finished downloading or can run.
After installation, npm should record Cypress under devDependencies and update the lockfile used by the project. Keep those files in version control so other developers and CI can install the same dependency. Avoid installing Cypress globally for a project: a local dependency makes the project’s intended version available through npm’s project command resolution.
Open Cypress and complete first-run setup
From the same project root, launch the interactive app:
npx cypress openThe Cypress Launchpad lets you choose end-to-end (E2E) or component testing, select a browser, and start writing tests. For a new project, it generates the configuration and folder structure needed for the selected testing type. Follow the prompts in the Launchpad and use its browser selection rather than assuming that every browser installed on the computer is supported in every environment.
The first-run experience is interactive; it is not the command used to run a suite unattended in CI. Once the project is configured, test files can be added to the structure Cypress creates. The exact test setup depends on whether you chose E2E or component testing and on the application you are testing.
Free tools Windows power users keep installed
One-click scans. No signup required.
Run tests headlessly
To execute Cypress without opening the interactive app, run:
npx cypress runThis is the usual command for automated runs. It executes the tests using the project’s Cypress configuration and is suitable for CI once the application under test is available. If the application needs a development server, start it and wait until it is responding before invoking Cypress; merely starting the server process does not guarantee the application is ready.
Add convenient npm scripts
You can define project scripts in package.json so developers and CI use consistent commands:
{
"scripts": {
"cy:open": "cypress open",
"cy:run": "cypress run"
}
}Then launch the interactive app with npm run cy:open or run tests with npm run cy:run. Do not name a script cypress: a package-manager script with that name can shadow resolution of the Cypress binary and cause confusing command behavior.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Understand the package and binary installation
The npm dependency provides Cypress’s CLI and application version information. The platform-matched binary is downloaded separately, usually by the package’s post-install lifecycle script, into a global cache rather than being stored as ordinary project source files. Cypress provides commands for explicitly installing that binary and checking that the installation is executable.
If an installation policy blocks lifecycle scripts, if the install command used --ignore-scripts, or if CI restored an incomplete cache, the package can be present while Cypress reports that its binary is unavailable. Use the explicit sequence below from the project root:
npm install cypress --save-dev
npx cypress install
npx cypress verify
npx cypress opennpx cypress install downloads the binary matching the project’s Cypress npm package. npx cypress verify checks that Cypress is installed correctly and executable. If verification fails, resolve that problem before treating a later browser-launch error as a test configuration issue.
Handle npm 11 and npm 12 lifecycle-script policies
Cypress’s current installation guidance identifies a change in npm lifecycle-script handling: npm 11.16.0 warns about lifecycle scripts, while npm 12.0.0 blocks them by default. As a result, a normal-looking package installation may not run the script that downloads Cypress’s binary.
- If npm asks whether Cypress may run installation scripts, approve Cypress in npm’s
allowScriptsconfiguration, then rebuild as needed so the install lifecycle can run. - If scripts were blocked or disabled, run
npx cypress installexplicitly after the package installation. - Run
npx cypress verifyto confirm the binary is present and executable, then retrynpx cypress openornpx cypress run.
Do not assume that rerunning the package install alone will fix a lifecycle-policy restriction; the policy may block the same script again. If your organization manages npm configuration centrally, follow its approval process rather than changing shared settings without authorization.
Install and run Cypress in CI
A basic CI flow installs the project dependencies and runs Cypress from the repository:
npm install cypress --save-dev
npx cypress runIn a real pipeline, install the project from its lockfile using the package manager’s reproducible-install approach, and ensure the Cypress binary is available to the job. If lifecycle scripts are disabled by policy or a cache contains only the npm package, add an explicit npx cypress install step before running tests.
The application server must be running and ready before Cypress starts. A command such as npm start & npx cypress run can race: the test command may begin before the server has finished starting. Use a readiness mechanism that waits for the application to respond, or the Cypress GitHub Action’s start and wait-on options, as documented in Cypress’s CI guidance. This separates two failures that are easy to confuse: Cypress may be installed correctly while the app URL is not yet available.
For repeatable CI, make the environment explicit: use a supported Node.js and operating-system combination, install dependencies from the checked-in lockfile, ensure the Cypress binary cache is complete or install the binary, start the application, wait for readiness, and then run the suite. When a job fails, inspect whether it failed during dependency installation, binary verification, browser startup, application readiness, or a test assertion; each points to a different fix.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot common installation and launch failures
The cypress package exists, but Cypress says the binary is missing
The binary download may have been skipped, blocked, or left out of a cache. Run npx cypress install, followed by npx cypress verify. Check whether npm lifecycle scripts were disabled with --ignore-scripts or restricted by the current npm policy.
npm reports a lifecycle-script warning or does not download the binary
With the npm 11/12 behavior described above, approve Cypress in allowScripts and rebuild if appropriate, or explicitly install the binary with npx cypress install. A successful package install is not proof that its post-install download ran.
Cypress will not run on this machine
Compare the machine’s Node.js, npm, operating system, and architecture with the current Cypress requirements. Pay particular attention to Linux distribution and arm64 support. If the platform or runtime is unsupported, use a supported environment instead of repeatedly reinstalling the same package.
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 →The command works in one terminal but not another
Confirm that the terminal is in the project root and that the project dependency has been installed there. Use npx cypress or a project script such as npm run cy:run so the project-local version is selected. Also check whether a script named cypress is shadowing the executable.
CI starts but cannot reach the application
Check that the server command actually starts the expected app and that the configured URL is reachable from the CI job. Add a readiness wait before npx cypress run; starting a server in the background and immediately starting tests is subject to a race condition.
Cypress opens, but the tests fail
Once npx cypress verify succeeds and the app is reachable, distinguish setup failures from test failures. Confirm that the Launchpad generated the testing mode and configuration you intended, that the selected browser is available, and that the tests target the running application. A test assertion failure is not repaired by reinstalling the Cypress binary.
Or skip the browser setup
Cypress is for browser testing; if the job is simply to capture a page as an image or PDF, a screenshot API can avoid setting up a local browser. ScreenshotNeo is a separate screenshot service, not a Cypress replacement. One GET request returns a PNG, JPEG, WebP, or PDF, and its API options are documented at ScreenshotNeo’s API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000, and every feature is available on every plan. Learn more at ScreenshotNeo. Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Does installing Cypress add test files to my application?
The Launchpad generates the configuration and folder structure during first-run setup; the npm install command itself adds the dependency.
Can I use Cypress without choosing a browser in the Launchpad?
The first-run Launchpad prompts you to select a browser. Browser availability depends on the environment and Cypress support for it.
Is Cypress’s binary stored in the project folder?
The binary is normally downloaded to a global cache, while the npm module is a local project dependency.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, 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 minuteQuick 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.
