# How to Set Up the Cypress Monorepo Locally: A Complete Development Guide

> Learn how to set up the Cypress monorepo locally. Follow our complete guide to clone the repo, install dependencies, and start local development for the Cypress application.

- Repository: [Cypress.io/cypress](https://github.com/cypress-io/cypress)
- Tags: how-to-guide
- Published: 2026-08-06

---

**Clone the cypress-io/cypress repository, install Node and Yarn 1.x, run `yarn` and `yarn dev`, then launch the GUI with `yarn start` to begin local development.**

The Cypress monorepo is a complex, multi-workspace repository containing the desktop application, CLI, internal packages, and extensive tooling. Whether you're fixing bugs, adding features, or exploring how Cypress works under the hood, this guide walks through the complete setup process based on the official source code in `cypress-io/cypress`.

## Cypress Monorepo Architecture

Understanding the repository structure helps navigate development tasks efficiently. The project is organized into distinct workspaces, each with specific responsibilities:

### Key Workspaces

- **`cli/`** – The main `cypress` npm package and component-testing adapters
- **`packages/`** – Core internal packages including driver, server, proxy, rewriter, and launcher
- **`npm/`** – Publicly published npm packages (webpack-dev-server, vite-dev-server, plugins)
- **`tooling/`** – Build tooling for V8 snapshots and packherd
- **`system-tests/`** – Full end-to-end tests running against built Cypress binaries
- **`scripts/`** – Build, release, and CI automation scripts

Each workspace operates under different runtime constraints. The CLI runs on Node, the desktop app on Electron, and the driver in browsers. The *Runtime Targets* section in [[`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md)](https://github.com/cypress-io/cypress/blob/develop/AGENTS.md) documents these constraints in detail.

## Prerequisites for Cypress Monorepo Setup

Before running any commands, verify these requirements from the repository source files:

| Requirement | Source Location |
|-------------|-----------------|
| **Node version** | Root [`.node-version`](https://github.com/cypress-io/cypress/blob/develop/.node-version) file |
| **Yarn 1.x** | [[`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md) Prerequisites section](https://github.com/cypress-io/cypress/blob/develop/AGENTS.md) |
| **Git** | Standard client for cloning |

**Critical:** Cypress requires Yarn 1.x specifically (`yarn@1.22.22`). Using Yarn 2+ or npm will cause installation failures.

## Step-by-Step Cypress Monorepo Installation

Follow this exact sequence to set up the repository locally:

```bash

# 1. Clone the repository

git clone https://github.com/cypress-io/cypress.git
cd cypress

# 2. Switch to the required Node version

nvm install
nvm use

# 3. Install dependencies across all workspaces

yarn

# 4. Build the monorepo (recommended after fresh install)

yarn build

# 5. Start development mode with live rebuilds

yarn dev

# 6. Launch the Cypress GUI

yarn start

```

### Command Reference

| Command | Purpose | Source |
|---------|---------|--------|
| `nvm use` | Reads `.node-version` and sets active Node version | `.node-version` |
| `yarn` | Installs workspace dependencies, runs post-install hooks, patches packages, rebuilds native modules | [`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md) Prerequisites |
| `yarn build` | Full monorepo build via Lerna—compiles TypeScript, creates V8 snapshots, bundles Electron app | [`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md) Build section |
| `yarn dev` | Watch mode for `@packages/app` and `@packages/launchpad` with Vite, launches Electron runner | [`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md) Common Commands |
| `yarn start` | Opens Cypress Launchpad GUI using dev bundles | [`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md) Common Commands |

The `yarn` command is particularly intensive. It rebuilds native modules including `better-sqlite3` and generates V8 snapshots. Initial installation may take several minutes.

## Running Tests in the Cypress Monorepo

The repository uses both **Vitest** and **Mocha** for different test suites. Run tests for specific packages rather than the entire repository:

```bash

# Run unit tests for the server package

yarn workspace @packages/server test-unit

# Run Vitest tests for the config package

yarn workspace @packages/config test

# Run end-to-end tests against a sample project

yarn cypress:run -- --project ./system-tests/projects/webpack5_wds4-react --browser chrome --headless

# Run component tests using built-in dev server

yarn cypress:run:ct -- --spec "cypress/component/**/*.spec.ts"

```

The *Testing* section in [[`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md)](https://github.com/cypress-io/cypress/blob/develop/AGENTS.md) contains the complete command reference.

## Common Setup Issues and Solutions

### Post-Install Hook Failures

The initial `yarn` runs extensive post-install scripts. Interrupting this process can corrupt the workspace. If this occurs, simply re-run `yarn` to resume.

### Path-Dependent Test Failures

Tests in `@packages/config` require the workspace directory to contain the word "cypress". If you cloned into a folder with a different name, these tests fail intentionally. Either rename your folder or skip those specific tests.

### Linux/macOS Xvfb Requirements

Headless Electron execution requires an X virtual framebuffer. The repository's Docker image starts Xvfb on `DISPLAY=:1` automatically. For local Linux development without a display, install and run Xvfb manually.

## Essential Files for Local Development

| File | Purpose | Location |
|------|---------|----------|
| `.node-version` | Exact Node version requirement | Repository root |
| [`package.json`](https://github.com/cypress-io/cypress/blob/main/package.json) | Workspace configuration, Lerna scripts | Repository root |
| [`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md) | Monorepo overview, commands, runtime targets | Repository root |
| [`guides/README.md`](https://github.com/cypress-io/cypress/blob/main/guides/README.md) | Links to per-package documentation | `guides/` |
| [`packages/app/README.md`](https://github.com/cypress-io/cypress/blob/main/packages/app/README.md) | Vue-based Launchpad GUI documentation | `packages/app/` |
| [`packages/server/README.md`](https://github.com/cypress-io/cypress/blob/main/packages/server/README.md) | HTTP server powering test runs | `packages/server/` |
| [`npm/vite-dev-server/README.md`](https://github.com/cypress-io/cypress/blob/main/npm/vite-dev-server/README.md) | Vite integration for component testing | `npm/vite-dev-server/` |

## Summary

- **Clone** the `cypress-io/cypress` repository and navigate into it
- **Install** the exact Node version from `.node-version` using `nvm`
- **Use Yarn 1.x exclusively**—other package managers are unsupported
- **Run `yarn`** to install all workspace dependencies and native module rebuilds
- **Execute `yarn build`** for full TypeScript compilation and V8 snapshot generation
- **Start `yarn dev`** for watch-mode development with live rebuilding
- **Launch `yarn start`** to open the Cypress GUI in development mode
- **Test selectively** using workspace-specific commands rather than monorepo-wide test runs

## Frequently Asked Questions

### What Node version does the Cypress monorepo require?

The required version is declared in the root [`.node-version`](https://github.com/cypress-io/cypress/blob/develop/.node-version) file. Use `nvm install` and `nvm use` to automatically switch to this version. The repository tracks specific Node versions for compatibility with Electron and native module compilation.

### Can I use npm or Yarn 2+ to install Cypress monorepo dependencies?

No. According to [[`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md)](https://github.com/cypress-io/cypress/blob/develop/AGENTS.md), Cypress specifically requires Yarn 1.x (`yarn@1.22.22`). The workspace configuration, post-install scripts, and native module rebuilds depend on Yarn 1.x behavior. Using alternatives will cause installation and build failures.

### How long does the initial `yarn install` take?

Expect 5–15 minutes depending on hardware. The installation rebuilds native modules including `better-sqlite3`, applies patches via `patch-package`, deduplicates dependencies, and generates V8 snapshots. Do not interrupt this process; if corrupted, re-run `yarn` to recover.

### Why do some tests fail if my folder isn't named "cypress"?

The `@packages/config` test suite contains path-dependent assertions that verify the workspace directory name. This is intentional behavior for testing configuration resolution. Rename your clone folder to "cypress" or exclude those specific tests from your run.