Install Cypress on Mac: Step-by-Step Guide

To install Cypress on a Mac, you need Node.js (version 18 or newer) and npm, then run npm install cypress --save-dev in your project folder. After installation, launch it with npx cypress open to start the Test Runner. This guide walks through the entire setup, from prerequisites to troubleshooting common errors.

Prerequisites: What You Need Before Installing

Cypress is a JavaScript-based end-to-end testing framework that runs locally on your machine. Before installing, ensure your Mac meets these requirements:

Node.js: Version 18 or higher (LTS versions are recommended). Check with node -v in Terminal.
npm: Comes with Node.js, but verify with npm -v.
macOS: Cypress supports macOS 10.9 and above, but the latest versions work best on recent macOS releases (Catalina or newer).
Disk space: Cypress downloads a binary (~200 MB) plus the npm package, so ensure at least 1 GB free.
Internet connection: Needed for the initial download and for updating Cypress.

If you don’t have Node.js, install it via the official installer from nodejs.org or use Homebrew with brew install node. Using a version manager like nvm is also a good practice to avoid permission issues.

Step-by-Step Installation Process

Open Terminal and navigate to your project directory (or create a new one). Then follow these steps:

Initialize your project (if needed): Run npm init -y to create a package.json file.
Install Cypress as a dev dependency: Run npm install cypress --save-dev. This installs the Cypress npm package and downloads the Cypress binary to your machine.
Verify the installation: Run npx cypress --version to see the installed version. If you see version numbers, the installation succeeded.
Launch Cypress: Run npx cypress open to open the Test Runner. On first launch, Cypress creates a cypress folder with example tests and a configuration file (cypress.config.js).
Run tests headlessly (optional): Use npx cypress run to execute all tests in the terminal without the GUI.

If you prefer a global installation, you can run npm install -g cypress, but local installation is recommended to keep dependencies per-project.

Understanding the Cypress Directory Structure

After the first launch, Cypress creates the following structure in your project:

cypress/e2e/ – where your test files (e.g., home.cy.js) live.
cypress/fixtures/ – for static test data (JSON, images, etc.).
cypress/support/ – for custom commands and global configuration (e.g., commands.js).
cypress.config.js – the main configuration file where you set base URL, viewport, etc.

This structure is automatically generated and is the standard layout for Cypress projects. You can modify the config file to change default settings, such as the base URL for your app.

Common Installation Issues and How to Fix Them

Even with a straightforward process, you might encounter a few hiccups. Here are the most frequent problems and their solutions:

EACCES permission errors: This happens when npm tries to write to global directories without permission. Fix it by installing Node via nvm (which avoids permission issues) or by running sudo npm install -g cypress (use with caution).
Download hangs or fails: Cypress downloads its binary from a CDN. If it stalls, check your internet connection or proxy settings. You can also set the environment variable CYPRESS_DOWNLOAD_MIRROR to a mirror if you’re in a restricted network.
Missing dependencies on Linux (not Mac): While this guide is for Mac, if you’re on Linux, you might need additional libraries like libgtk2.0-0 and libnotify-bin. On Mac, these are not required.
Node version too old: If you get an error about unsupported Node version, update Node.js to a newer LTS version.
Cypress not opening: If npx cypress open doesn’t launch the GUI, try npx cypress verify to check the binary integrity, then run npx cypress install to re-download if needed.

Running Your First Test

Once Cypress is installed, you can write and run a simple test to confirm everything works. Create a file cypress/e2e/first.spec.js (or use the default example) with the following content:

describe('My First Test', () => {
  it('Visits the Cypress website', () => {
    cy.visit('https://example.cypress.io')
    cy.contains('type').click()
    cy.url().should('include', '/commands/actions')
  })
})

Then run npx cypress open and click on the test file in the Test Runner. You’ll see the test execute in a real browser (Electron by default). You can also run it headlessly with npx cypress run.

Cypress vs. Other Testing Tools

Cypress is often compared to Selenium, Playwright, and Puppeteer. Here’s a quick comparison to help you understand where Cypress fits:

Cypress: Runs in the same process as your app, giving it fast execution and the ability to mock network requests. It has a rich interactive runner and time-travel debugging. It’s designed primarily for end-to-end testing.
Selenium: The classic automation tool, supports multiple languages and browsers, but requires a WebDriver server and is generally slower and more brittle.
Playwright: A newer competitor, also fast and reliable, with support for multiple browsers and parallel execution. It uses a different architecture (out-of-process) and is great for cross-browser testing.
Puppeteer: A Node library for controlling Chrome/Chromium, more low-level and not a full testing framework.

Choose Cypress if you want a developer-friendly, all-in-one testing framework with great debugging and a built-in test runner. It’s especially popular for React, Vue, and Angular apps.

Cost and Licensing

Cypress is open-source and free to use for any project, including commercial ones. The core framework is released under the MIT license. There is also a paid service called Cypress Cloud (formerly Cypress Dashboard) that offers features like parallelization, test recording, and analytics, but it’s optional. You can use Cypress entirely locally without any cost.

Frequently Asked Questions

Do I need to install Cypress globally?

No, local installation is recommended. Installing locally ensures each project uses its own version, avoiding conflicts. You can still run Cypress via npx, which uses the local installation.

Can I install Cypress without Node.js?

No, Cypress requires Node.js because it’s a Node-based tool. Even if you only write tests in JavaScript, the framework itself runs on Node.

How do I update Cypress to a new version?

Run npm install cypress@latest --save-dev in your project. This will update the package and download the new binary. You can check the current version with npx cypress --version.

Why does Cypress download a binary on install?

Cypress is a standalone application that runs in a browser. The npm package is just a wrapper; the actual executable is downloaded as a binary to your machine. This is why the installation can take a few minutes.

Can I use Cypress with TypeScript?

Yes, Cypress has built-in TypeScript support. You can write your tests in TypeScript without any extra configuration. Just create .ts files in the cypress/e2e folder and Cypress will handle the transpilation.

What if I get a “Cypress cannot run because this binary is not installed” error?

This usually means the binary download failed or was corrupted. Run npx cypress install to force a re-download. If that doesn’t work, delete the Cypress cache (usually in ~/Library/Caches/Cypress) and reinstall.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →