# Cypress Configuration Options: Complete Guide to the Config System

> Explore comprehensive Cypress configuration options. Learn about default values and validation rules for effective test automation. Discover the complete Cypress config system.

- Repository: [Cypress.io/cypress](https://github.com/cypress-io/cypress)
- Tags: api-reference
- Published: 2026-06-21

---

**Cypress configuration options are centrally defined in the `@packages/config` package within [`packages/config/src/options.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/options.ts), where they follow the `ConfigOption` interface with validation rules, default values, and restart requirements.**

The cypress-io/cypress repository organizes its configuration system into two distinct categories—**DriverConfigOption** and **RuntimeConfigOption**—that control everything from browser viewport settings to internal runtime flags. Whether you define settings in a `cypress.config.{js|ts|mjs}` file, pass them via the CLI `--config` flag, or modify them at runtime with `Cypress.config()`, every option is validated against strict schemas in [`packages/config/src/validation.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/validation.ts).

## Core Configuration Architecture

The configuration system resides entirely within the `@packages/config` package, with [`packages/config/src/options.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/options.ts) serving as the single source of truth for all available Cypress configuration options.

### Driver vs. Runtime Configuration Options

Cypress splits its configuration into two functional groups:

- **DriverConfigOption**: Options defined in the `driverConfigOptions` array that affect the test driver, browser behavior, or server settings. These can require a server or browser restart when modified and include settings like `baseUrl`, `viewportWidth`, and `defaultCommandTimeout`.
- **RuntimeConfigOption**: Options defined in the `runtimeOptions` array that are read-only at launch or used internally, such as `configFile`, `cypressBinaryRoot`, and `isInteractive`.

### The ConfigOption Interface

Every Cypress configuration option follows the `ConfigOption` interface structure declared in [`options.ts`](https://github.com/cypress-io/cypress/blob/main/options.ts). Key fields include:

- **`defaultValue`**: A static value or function that can vary by testing type (`e2e` vs `component`).
- **`validation`**: A function from [`packages/config/src/validation.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/validation.ts) (e.g., `validate.isNumber`, `validate.isStringOrArrayOfStrings`) that enforces type safety.
- **`overrideLevel`**: Controls mutability—`'any'` allows per-test overrides, `'suite'` restricts to per-suite, and `'never'` prevents changes.
- **`requireRestartOnChange`**: Specifies whether changing the option forces a `'server'` or `'browser'` restart.
- **`isExperimental`**: Boolean flag marking feature-gated options that hide from the UI unless explicitly enabled.

## Essential Cypress Configuration Options

The `driverConfigOptions` array contains the public API surface that most developers interact with. Here are the critical settings that control test execution:

### Network and Browser Settings

- **`baseUrl`**: String defaulting to `null`. Sets the base URL for `cy.visit()` commands. Changing this value requires a **server restart** according to the source code.
- **`viewportWidth`** / **`viewportHeight`**: Numeric defaults that differ by testing type—`1000`/`660` for e2e tests and `500` for component tests. These dimensions configure the browser viewport in the test runner.

### Test Execution Behavior

- **`defaultCommandTimeout`**: Defaults to `4000` ms. Defines the timeout for most Cypress commands. Because its `overrideLevel` is set to `'any'`, you can modify this per-test or per-suite.
- **`specPattern`**: Glob pattern defaulting to `cypress/e2e/**/*.cy.{js,jsx,ts,tsx}` for e2e tests or `**/*.cy.{js,jsx,ts,tsx}` for component tests. Determines which test files Cypress discovers.
- **`supportFile`**: Path to the support file automatically loaded before tests run—`cypress/support/e2e.{js,jsx,ts,tsx}` for e2e or `cypress/support/component.{js,jsx,ts,tsx}` for component testing.

### Recording and Debugging

- **`video`**: Boolean defaulting to `false`. Enables video recording of the entire test run.
- **`screenshotOnRunFailure`**: Boolean defaulting to `true`. Automatically captures screenshots when tests fail.
- **`retries`**: Object defaulting to `{ runMode: 0, openMode: 0 }`. Configures automatic retry attempts for flaky tests in both headless and interactive modes.

### Experimental and Advanced Options

- **`experimental*`**: Various boolean flags (e.g., `experimentalOriginDependencies`) that gate upcoming features. These options are hidden from the Cypress UI unless the specific experiment is enabled.
- **`testIsolation`**: Boolean defaulting to `true` that controls whether each test runs in a clean browser context. Restricted to `'suite'` level override, meaning it cannot be changed per-test, and is not allowed for component testing.

## Configuration Validation and Breaking Changes

Cypress employs a strict validation pipeline to ensure configuration integrity. When loading a config file, the system:

1. **Loads defaults** from the `options` array in [`packages/config/src/options.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/options.ts).
2. **Merges** user-provided values from the config file, CLI arguments, or runtime API.
3. **Validates** each entry using pure validation functions from [`packages/config/src/validation.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/validation.ts) that return `true` on success or descriptive error objects on failure.
4. **Detects breaking options** by checking against `breakingOptions`, `breakingRootOptions`, and `testingTypeBreakingOptions` arrays. When deprecated options like `experimentalJitCompile` appear, Cypress throws specific error keys (e.g., `EXPERIMENTAL_JIT_COMPILE_REMOVED`).

## How to Configure Cypress

### Using cypress.config.js with defineConfig

The standard approach uses `defineConfig` from the `cypress` package to export your settings with full TypeScript support and validation:

```javascript
// cypress.config.js
const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.spec.js',
    defaultCommandTimeout: 8000,
    video: true,
  },
  // Driver-level option requiring server restart when changed
  retries: { runMode: 2, openMode: 1 },
  // Experimental flag gated by feature availability
  experimentalOriginDependencies: true,
})

```

### CLI Overrides

You can override any configuration option directly from the command line using the `--config` flag with comma-separated key-value pairs:

```bash

# Target specific tests with custom baseUrl and video recording

cypress run --spec "cypress/e2e/login.spec.js" \
            --config baseUrl=https://staging.example.com,video=true

```

### Runtime Configuration Changes

For options with `overrideLevel: 'any'`, modify values dynamically within your test code using `Cypress.config()`:

```javascript
// Inside a test file
Cypress.config('defaultCommandTimeout', 12000)  // Allowed: overrideLevel = 'any'

```

Note that options marked with `'never'` or `'suite'` for `overrideLevel` will throw errors if you attempt to change them at this scope.

## Summary

- **Cypress configuration options** are declared in [`packages/config/src/options.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/options.ts) as either `DriverConfigOption` or `RuntimeConfigOption` instances.
- Each option enforces type safety through validation functions in [`packages/config/src/validation.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/validation.ts) and supports dynamic defaults based on testing type.
- **Driver options** like `baseUrl` and `viewportWidth` can require server or browser restarts when changed, while **runtime options** are internal or read-only at launch.
- Configuration supports multiple override levels: via `cypress.config.{js|ts|mjs}`, CLI `--config` flags, or at runtime with `Cypress.config()` for options marked with `overrideLevel: 'any'`.
- Breaking changes are detected through dedicated arrays (`breakingOptions`, `breakingRootOptions`) that emit specific error keys when deprecated options are encountered.

## Frequently Asked Questions

### Where are Cypress configuration options defined?

Cypress configuration options are defined in the `@packages/config` package, specifically within [`packages/config/src/options.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/options.ts). This file exports two arrays—`driverConfigOptions` and `runtimeOptions`—that contain every valid configuration property, its default value, validation function, and metadata about restart requirements.

### What is the difference between driver and runtime config options?

**DriverConfigOption** settings affect the test driver, browser behavior, or server state, and they often require a restart when modified. Examples include `baseUrl`, `viewportWidth`, and `defaultCommandTimeout`. **RuntimeConfigOption** settings are internal flags or read-only values set at launch, such as `configFile` or `cypressBinaryRoot`, which cannot be changed after Cypress initializes.

### How do I override Cypress configuration at runtime?

You can override configuration at runtime using `Cypress.config('key', value)` inside your test files, but only for options where `overrideLevel` is set to `'any'` in the source definition. Options marked `'suite'` can only be changed in suite-level hooks, while those marked `'never'` cannot be modified at runtime. Attempting to override restricted options will result in runtime errors.

### What happens when I change an option that requires a restart?

When you modify a configuration option where `requireRestartOnChange` is set to `'server'` or `'browser'` (such as `baseUrl`), Cypress must restart the affected component to apply the change. In the interactive mode (`cypress open`), this happens automatically. In `run` mode, you must restart the Cypress process to pick up the new configuration value.