From your project root, install Cypress as a development dependency with npm install cypress --save-dev, then run npx cypress open to launch the Cypress Launchpad. Choose end-to-end (E2E) or component testing and select a browser. For headless test execution, use npx cypress run. If the Cypress npm package installs but its binary does not, run npx cypress install explicitly and verify it with npx cypress verify.
Before you install: check Node.js, npm, and your operating system
Cypress is installed into a project with npm, but whether it can run also depends on the supported Node.js, npm, and operating-system versions. The current Cypress guide lists Node.js 22.x, 24.x, or 26.x and later, and npm 10.1.0 or later. Those requirements can change, so check Cypress’s current requirements before installing, especially if you are using an older development machine or a CI runner.
The guide lists macOS 13.5 or later, Windows 10/11 x64, and supported Linux distributions, including Ubuntu 22.04 or later. Linux support has arm64 caveats: check the current platform details for your specific distribution and architecture rather than assuming that every Linux or ARM environment is supported. An npm install succeeding does not by itself establish that your operating system and browser setup can run Cypress.
Install Cypress in your project
- Open a terminal in the project root. This should be the directory containing the application’s
package.json. If the project does not yet have a package file, initialize it with your project’s normal npm setup before adding a development dependency. - Install Cypress locally:
npm install cypress --save-dev - Let npm finish. Cypress adds the
cypressnpm module to the project as a development dependency. Its install lifecycle normally also downloads the matching Cypress binary to a global cache. The npm module and that binary are related parts of the installation, but they are not the same thing. - Open the app:
npx cypress open
Using --save-dev records Cypress as a development-only project dependency, rather than as an application runtime dependency. Keeping the dependency local makes the project’s Cypress version explicit and available to the project’s npm commands.
Recommended Free Tools
Open Cypress and finish first-run setup
The first interactive launch starts the Cypress App and Launchpad. Choose whether this project will use end-to-end testing or component testing, then select a browser. The Launchpad guides you through creating the configuration and folder structure needed for the selected setup. These choices are project setup; installing the npm package alone does not create and configure the tests you intend to run.
- Run
npx cypress openfrom the project root. - In the Launchpad, choose E2E Testing or Component Testing.
- Follow the prompts to generate the configuration and folder structure.
- Select a browser and continue into the Cypress interface to start writing or running tests.
Use the browser option that is available and appropriate for your environment. If the Launchpad cannot proceed, first check the operating-system and browser compatibility information in Cypress’s current requirements, rather than treating a completed npm install as proof that the full setup is supported.
Run tests headlessly
To execute Cypress tests without opening the interactive app, run this from the project root:
npx cypress run
This is the command to use for a headless run, including a basic CI invocation. It is distinct from npx cypress open: the latter launches the interactive app and first-run setup, while cypress run executes tests headlessly. If you have not yet completed the Launchpad setup, open Cypress first so it can create the configuration and folder structure.
If npm installed the package but the Cypress binary is missing
The package install normally downloads the matching binary through an npm lifecycle script. That postinstall download can be prevented by npm’s script policy, by installing with --ignore-scripts, or by a CI setup that caches or skips the binary installation. In those cases, npm may have recorded the Cypress dependency even though the executable binary is not available.
Use this sequence from the project root to install and check both parts:
npm install cypress --save-devnpx cypress installnpx cypress verifynpx cypress open
cypress install installs the binary matching the installed npm package. cypress verify checks that Cypress is installed correctly and executable. Run the explicit install step when a lifecycle-script restriction or CI caching prevented the automatic download; it is not a replacement for installing the npm dependency itself.
npm 11.16.0 and npm 12 lifecycle-script behavior
Cypress’s current installation guidance says npm 11.16.0 warns about lifecycle scripts and npm 12.0.0 blocks them by default. If you are on an affected npm version and the binary was not downloaded, approve Cypress in npm’s allowScripts configuration and rebuild, or run npx cypress install explicitly after the package installation. Follow the current npm and Cypress instructions for the exact approval and rebuild commands for your installed versions; lifecycle-script handling is version-sensitive.
Add npm scripts for repeatable commands
You can put the common commands in the project’s package.json so that opening Cypress and running it headlessly are easy to remember:
{
"scripts": {
"cy:open": "cypress open",
"cy:run": "cypress run"
}
}Then run npm run cy:open for interactive setup or npm run cy:run for a headless run. Avoid naming a script simply cypress; that name can shadow the Cypress binary during package-manager command resolution.
Install and run Cypress in CI
A basic CI setup installs the local dependency and then runs Cypress:
npm install cypress --save-dev
npx cypress runBefore the Cypress command, start the application under test and wait until it is ready to respond. Starting the server in the background and immediately launching Cypress—for example, npm start & npx cypress run—can race: Cypress may begin before the app is available. Use a readiness mechanism, or the official Cypress GitHub Action’s start and wait-on options, so the test run begins only after the server is ready.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Also account for the binary separately from the npm package in CI. If the job’s npm policy blocks lifecycle scripts or its cache strategy omits the Cypress binary, include the explicit npx cypress install step before verification or execution. If a CI run fails after a seemingly successful npm install, check for a missing binary and server readiness before changing test code.
Common installation and launch problems
- The package is present, but Cypress says the binary is missing. The npm lifecycle download may have been blocked, ignored, or skipped by CI. Run
npx cypress install, thennpx cypress verify. - npm warns about or blocks install scripts. With npm versions covered by Cypress’s current guidance, approve Cypress through npm’s
allowScriptsconfiguration and rebuild, or explicitly install the binary withnpx cypress install. npx cypress opendoes not launch a usable setup. Confirm you are running it from the project root, verify the binary withnpx cypress verify, and check that your Node.js, npm, OS, and architecture meet the current Cypress requirements.- Headless CI starts before the application is ready. Replace an immediate background start-and-run sequence with a readiness check or the GitHub Action’s
startandwait-onoptions. - A Linux or ARM installation behaves differently from a local desktop install. Check the current Cypress platform requirements for the exact distribution and architecture; the general Linux listing includes arm64 caveats.
- An npm script cannot find the Cypress command as expected. Check for a script named
cypressthat may shadow the binary, and use names such ascy:openandcy:run.
Or skip the browser setup
If your goal is to capture a website screenshot rather than install Cypress to write browser tests, ScreenshotNeo is a separate screenshot API—not a Cypress installer or replacement for Cypress tests. One GET request returns an image or PDF. The example below uses the supplied Stripe URL; replace it with the page you need to capture. See the ScreenshotNeo API documentation for parameters and response details.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot; those steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response includes X-Page-Verdict and X-Billed headers. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000. Every feature is on every plan. Learn more at ScreenshotNeo, or sign up for the free plan.
What to remember about npm installation
The shortest working path for a local project is npm install cypress --save-dev, followed by npx cypress open for interactive setup. Use npx cypress run for headless execution. If the Cypress binary did not download, explicitly install it and verify it; in CI, also ensure the application server is ready before tests start.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteFrequently Asked Questions
Does installing the Cypress npm package also install the Cypress binary?
Normally its install lifecycle downloads the matching binary to a global cache, but npm lifecycle-script policy or installation options can prevent that download.
Can I run Cypress tests without opening the Cypress App?
Yes. Once the project is set up, run npx cypress run for headless execution.
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.
