# How to Override Default Cypress Configuration Settings: A Complete Guide

> Learn to override default Cypress configuration settings using CLI flags, cypress.config.js, or programmatically. Master runtime overrides for flexible testing.

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

---

**You can override default Cypress configuration settings via CLI flags (`--config`, `--config-file`), the [`cypress.config.js`](https://github.com/cypress-io/cypress/blob/main/cypress.config.js) file, or programmatically at runtime using `Cypress.config()` and suite-level overrides, with each option respecting an `overrideLevel` that restricts when changes are allowed.**

The **cypress-io/cypress** repository provides multiple extension points to customize default behavior without modifying core source code. Understanding how to override default Cypress configuration settings requires knowledge of the `overrideLevel` semantics that govern when and where each option can be changed. This guide examines the actual source implementation to show you exactly how to customize timeouts, viewport dimensions, base URLs, and other settings across CLI, config file, and test-run scopes.

## Understanding Configuration Architecture and Default Values

Cypress stores its default configuration values in **[`packages/config/src/options.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/options.ts)**, where every option is defined with a default value, validation function, and `overrideLevel` restriction. The `overrideLevel` property determines where an option can be modified:

- **`'any'`** – Can be changed via CLI, config file, or at test time
- **`'suite'`** – Only modifiable via `Cypress.config()` inside a suite or test
- **`'never'`** – Immutable at runtime; only settable at build time

For example, `baseUrl` uses `'any'` while `testIsolation` uses `'suite'` and `allowCypressEnv` uses `'never'`. When you attempt to override a value, **[`packages/config/src/browser.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/browser.ts)** validates the change against these levels using a lookup table generated by `createIndex`.

## CLI Overrides: --config and --config-file

### Overriding via --config Flag

Pass configuration values directly when running Cypress via the command line. The CLI parser defined in **[`cli/lib/cli.ts`](https://github.com/cypress-io/cypress/blob/main/cli/lib/cli.ts)** accepts the `--config` flag, which **[`cli/lib/exec/run.ts`](https://github.com/cypress-io/cypress/blob/main/cli/lib/exec/run.ts)** processes into the internal configuration object.

Use comma-separated key-value pairs for simple overrides:

```bash
cypress run --config "baseUrl=http://my.test,video=false,defaultCommandTimeout=8000"

```

Or pass a JSON string for complex values:

```bash
cypress run --config '{"video":false,"viewportWidth":1440}'

```

### Specifying Alternative Config Files

Use `--config-file` to load a completely different configuration file without renaming your defaults:

```bash
cypress run --config-file ./config/cypress.staging.config.ts

```

The path is forwarded to the config loader, which merges the exported values with defaults from [`options.ts`](https://github.com/cypress-io/cypress/blob/main/options.ts) using the same validation logic as the standard [`cypress.config.js`](https://github.com/cypress-io/cypress/blob/main/cypress.config.js) file.

## Config File Overrides: cypress.config.js and defineConfig

Create a `cypress.config.{js,ts,mjs}` file at your project root to override defaults persistently. Import `defineConfig` from Cypress to get TypeScript validation and autocompletion:

```typescript
// cypress.config.ts
import { defineConfig } from 'cypress'

export default defineConfig({
  baseUrl: 'http://localhost:3000',
  viewportWidth: 1280,
  viewportHeight: 800,
  video: false,
  defaultCommandTimeout: 10000,
  env: {
    API_TOKEN: 'test-token-123'
  }
})

```

During startup, the configuration loader validates each key against the schema in **[`packages/config/src/options.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/options.ts)** and merges your values with built-in defaults. Invalid values trigger validation errors before tests begin.

## Test-Time Overrides: Cypress.config() and Suite-Level Options

### Runtime Configuration with Cypress.config()

Inside your test code, call `Cypress.config()` to change values dynamically. This method is implemented in **[`packages/driver/src/util/config.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/util/config.ts)**, which enforces `overrideLevel` restrictions at runtime:

```javascript
describe('Admin Dashboard', () => {
  before(() => {
    // Override baseUrl for this suite only
    Cypress.config('baseUrl', 'http://admin.test')
  })

  it('loads the dashboard', () => {
    cy.visit('/dashboard')
    // Assertions here use the overridden baseUrl
  })
})

```

### Suite-Level Configuration Objects

Pass a configuration object as the second argument to `describe()` or `it()` to scope overrides to specific test blocks:

```javascript
describe('Responsive Layout', { viewportWidth: 1440 }, () => {
  it('renders correctly on large screens', () => {
    cy.visit('/')
    // This test runs with viewportWidth: 1440
  })
})

describe('Mobile View', { viewportWidth: 375, viewportHeight: 667 }, () => {
  it('works on phones', () => {
    cy.visit('/')
  })
})

```

Only options with `overrideLevel: 'any'` or `overrideLevel: 'suite'` can be used here. Attempting to override a `'never'` option generates a validation error.

## Validation and Error Handling

When you attempt an illegal override, **[`packages/driver/src/util/config.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/util/config.ts)** throws a validation error formatted by **[`packages/driver/src/cypress/error_messages.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/cypress/error_messages.ts)**. For example, trying to override `allowCypressEnv` (which has `overrideLevel: 'never'`) produces:

```javascript
// This will throw an error
describe('Invalid Suite', { allowCypressEnv: false }, () => {
  // Error: The config passed to your suite-level overrides has the following validation error...
})

```

The error message includes the specific key and the restriction (`overrideLevel: 'never'`), helping you identify which configuration layer is appropriate for your change.

## Summary

- **Default values** live in [`packages/config/src/options.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/options.ts) and include `overrideLevel` metadata restricting when values can be changed.
- **CLI overrides** use `--config` for inline JSON or comma-separated values, processed by [`cli/lib/exec/run.ts`](https://github.com/cypress-io/cypress/blob/main/cli/lib/exec/run.ts), or `--config-file` to specify alternative config files.
- **Config file overrides** export a `defineConfig` object from `cypress.config.{js,ts}` to merge persistent customizations with defaults.
- **Test-time overrides** use `Cypress.config()` or suite-level options in `describe()`/`it()` blocks, enforced by [`packages/driver/src/util/config.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/util/config.ts).
- **Validation** occurs at multiple layers: CLI parsing, config file loading, and runtime enforcement, with clear error messages for invalid overrides.

## Frequently Asked Questions

### Can I override any Cypress configuration option at runtime?

No. Each option has an `overrideLevel` defined in [`packages/config/src/options.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/options.ts). Options marked `'never'` cannot be changed at runtime; `'suite'` options only via `Cypress.config()` or suite-level overrides; and `'any'` options via CLI, config file, or runtime. Attempting to override a restricted option throws a validation error from [`packages/driver/src/util/config.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/util/config.ts).

### What is the difference between --config and --config-file flags?

The `--config` flag accepts inline configuration values as JSON or comma-separated key-value pairs for immediate overrides during a single run. The `--config-file` flag accepts a file path to a JavaScript or TypeScript configuration file that exports a complete config object, useful for maintaining separate environment-specific configurations (e.g., staging vs. production).

### How do I override configuration for a single test suite without affecting others?

Pass a configuration object as the second argument to `describe()` or `it()`. For example: `describe('Suite', { viewportWidth: 1200 }, () => { ... })`. This creates a scoped override that applies only to tests within that block. Alternatively, use `Cypress.config('key', value)` inside a `before()` hook to set values for the duration of that suite.

### Where does Cypress validate that my configuration values are correct?

Validation occurs in three stages: the CLI validates flag syntax in [`cli/lib/cli.ts`](https://github.com/cypress-io/cypress/blob/main/cli/lib/cli.ts); the config loader validates against schemas in [`packages/config/src/options.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/options.ts) when loading files; and the driver validates runtime overrides in [`packages/driver/src/util/config.ts`](https://github.com/cypress-io/cypress/blob/main/packages/driver/src/util/config.ts) against the `testOverrideLevels` lookup built by [`packages/config/src/browser.ts`](https://github.com/cypress-io/cypress/blob/main/packages/config/src/browser.ts).