# How to Run Cypress Tests in Headless Mode: Complete CLI Guide

> Learn how to run Cypress tests in headless mode using the Cypress CLI. Execute your tests without the GUI for faster feedback and CI integration. Get the complete guide now.

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

---

**Use the `cypress run` command to execute Cypress tests without the interactive GUI, automatically enabling headless mode with Electron or adding `--headless` for other browsers.**

The cypress-io/cypress repository provides a robust command-line interface for running end-to-end tests without a visible browser window. Understanding how to run Cypress tests in headless mode is essential for integrating with continuous integration pipelines and containerized environments where display servers are unavailable.

## Headless Execution Architecture

When you invoke `cypress run`, the system initializes a non-interactive session. In [`cli/lib/cypress.ts`](https://github.com/cypress-io/cypress/blob/main/cli/lib/cypress.ts), the CLI sets `config.isInteractive = false` immediately upon entry, signaling the server to bypass GUI-related services. The `@packages/launcher` component then determines the target browser and appends the appropriate `--headless` flag to the underlying driver.

The `@packages/server` module serves your test files, spawns the browser process, and coordinates WebSocket communication between the browser and Node process. Throughout this execution, the `@packages/config` system merges CLI flags with user configurations, ensuring the `headless` setting overrides any `headed` preferences. Upon completion, Cypress exits with code `0` for success or a non-zero code for failures, enabling reliable CI/CD orchestration.

## How to Run Cypress Tests in Headless Mode

### Basic Headless Execution

The default `cypress run` command launches Electron in headless mode automatically. No additional flags are required for the default configuration.

```bash

# Basic headless run (default Electron)

yarn cypress:run

```

### Browser-Specific Headless Configuration

To run Cypress tests in headless mode with Chrome, Firefox, Edge, or WebKit, explicitly pass the `--headless` flag alongside the `--browser` option.

```bash

# Headless run with a specific browser

yarn cypress:run -- --browser chrome --headless

```

For Chrome versions 112 and later, Cypress automatically forwards the `--headless=new` flag when detected, leveraging Chrome's updated headless implementation as documented in [`cli/CHANGELOG.md`](https://github.com/cypress-io/cypress/blob/main/cli/CHANGELOG.md).

### Targeting Specific Spec Files

Limit execution to individual test files using the `--spec` flag while maintaining headless operation.

```bash

# Run a single spec file in headless mode

yarn cypress:run -- --spec "cypress/e2e/login.cy.js" --headless

```

### CI/CD Integration Patterns

Configure your pipeline to fail builds on test failures using exit codes. According to [`AGENTS.md`](https://github.com/cypress-io/cypress/blob/main/AGENTS.md), standard headless execution returns appropriate exit codes, while `--posix-exit-codes` provides standardized behavior for automation environments.

```bash

# CI-friendly command (fails the build on test failures)

npm run cypress:run -- --headless --record --key $CYPRESS_RECORD_KEY

```

## Configuration and Browser Support

The headless mode configuration flows through several key components:

- **CLI Parser** ([`cli/lib/cypress.ts`](https://github.com/cypress-io/cypress/blob/main/cli/lib/cypress.ts)): Parses flags and sets `isInteractive: false`
- **Browser Launcher** (`packages/launcher`): Appends native headless flags to browser binaries for Chrome, Firefox, Edge, and WebKit
- **Configuration Merger** (`packages/config`): Resolves conflicts between `headless` and `headed` options, with `headless` taking precedence

Video recording, screenshots, and reporter output function identically in headless mode. Assets are written to the configured `videosFolder` and `screenshotsFolder` regardless of GUI availability.

## Summary

- Execute `cypress run` to run Cypress tests in headless mode without GUI dependencies
- The CLI automatically sets `config.isInteractive = false` in [`cli/lib/cypress.ts`](https://github.com/cypress-io/cypress/blob/main/cli/lib/cypress.ts)
- Add `--headless` explicitly when using Chrome, Firefox, Edge, or WebKit browsers
- Chrome 112+ users benefit from automatic `--headless=new` flag forwarding
- Exit codes (0 for success, non-zero for failures) enable reliable CI/CD integration
- Video recording and screenshots function identically to headed mode, outputting to `videosFolder` and `screenshotsFolder`

## Frequently Asked Questions

### What is the difference between `cypress open` and `cypress run`?

The `cypress open` command launches the interactive Test Runner GUI for local development, while `cypress run` executes tests in headless mode via the CLI. The latter sets `isInteractive` to false in the configuration and is designed for automation environments where no display server is available.

### Does headless mode support video recording and screenshots?

Yes. Video recording, screenshots, and reporter output function identically in headless mode. Assets are written to the configured `videosFolder` and `screenshotsFolder` regardless of whether the browser displays a GUI, as handled by the `@packages/server` module.

### How do I run headless tests in Chrome instead of Electron?

Pass the `--browser chrome` flag combined with `--headless`. Electron runs headless by default with `cypress run`, but Chrome, Firefox, Edge, and WebKit require explicit headless flags. The launcher in `packages/launcher` handles the browser-specific argument passing, including support for Chrome's `--headless=new` mode.

### Can I use headless mode in Docker containers?

Yes. Headless mode is specifically designed for environments without display servers, making it ideal for Docker containers and CI pipelines. The browser runs without X11 or other GUI dependencies, and the process exits with appropriate codes upon completion, as implemented in the [`cli/lib/cypress.ts`](https://github.com/cypress-io/cypress/blob/main/cli/lib/cypress.ts) entry point.