Environment:Cypress io Cypress Linux Display Server

Knowledge Sources	Cypress Xvfb issues Sandbox issues
Domains	Infrastructure, Linux, CI
Last Updated	2026-02-12 01:00 GMT

Overview

Linux display server environment with Xvfb (X Virtual Framebuffer) and Electron sandbox configuration for running Cypress headlessly in CI and server environments.

Description

On Linux, Cypress requires either a running X11 display server or Xvfb (X Virtual Framebuffer) to render browser content. The CLI automatically manages Xvfb lifecycle when no `DISPLAY` environment variable is set. Additionally, Electron requires the --no-sandbox flag on all Linux-like systems due to known Chromium sandbox compatibility issues. Ubuntu 24.04+ introduces unprivileged user namespace restrictions that must be disabled to prevent fatal sandbox errors.

Usage

Use this environment for running Cypress on Linux servers, CI pipelines (CircleCI, GitHub Actions, GitLab CI), Docker containers, and headless environments without a physical display. This is a mandatory prerequisite for all Linux-based test execution.

System Requirements

Category	Requirement	Notes
OS	Linux (any distribution)	Required for Xvfb; macOS and Windows handle display differently
Display Server	X11 with existing DISPLAY, or Xvfb	Cypress auto-starts Xvfb if DISPLAY is unset
Xvfb	`xvfb` package	Required when no X11 display is available
Screen Resolution	1280x1024x24 (default Xvfb)	Hardcoded in xvfb_args configuration
Kernel (Ubuntu 24.04+)	`apparmor_restrict_unprivileged_userns=0`	Must disable user namespace restrictions
Sandbox	--no-sandbox flag (auto-applied)	Applied automatically on all Linux-like systems

Dependencies

System Packages

`xvfb` — X Virtual Framebuffer for headless display
`libgtk2.0-0` or `libgtk-3-0` — GTK libraries for Electron rendering
`libasound2` — ALSA sound library (required by Electron)
`libgbm1` — GBM library for GPU buffer management
`libnss3` — Network Security Services
`libxss1` — X11 Screen Saver extension library
`libxtst6` — X11 Testing extension

Credentials

The following environment variables affect display server behavior:

`DISPLAY`: X11 display server address. When set, Cypress assumes a working X11 server and skips Xvfb. When unset, Cypress spawns its own Xvfb.
`XVFB_DISPLAY_NUM`: Override the Xvfb display number (default: auto-assigned).
`ELECTRON_RUN_AS_NODE`: When set, disables Xvfb requirement (indicates non-Electron context).

Quick Install

# Install Xvfb and Cypress system dependencies on Debian/Ubuntu
sudo apt-get install -y xvfb libgtk2.0-0 libgtk-3-0 libgbm-dev \
  libnss3 libxss1 libasound2 libxtst6

# For Ubuntu 24.04+, disable user namespace restrictions
echo "kernel.apparmor_restrict_unprivileged_userns=0" | sudo tee /etc/sysctl.d/60-apparmor-namespace.conf
sudo sysctl --system

# Run Cypress (Xvfb auto-managed)
npx cypress run

Code Evidence

Xvfb auto-detection and lifecycle from `cli/lib/exec/xvfb.ts:72-106`:

isNeeded (): boolean {
  if (process.env.ELECTRON_RUN_AS_NODE) {
    debug('Environment variable ELECTRON_RUN_AS_NODE detected, xvfb is not needed')
    return false // xvfb required for electron processes only.
  }
  if (os.platform() !== 'linux') {
    return false
  }
  if (process.env.DISPLAY) {
    const message = stripIndent`
      DISPLAY environment variable is set to ${process.env.DISPLAY} on Linux
      Assuming this DISPLAY points at working X11 server,
      Cypress will not spawn own Xvfb

      NOTE: if the X11 server is NOT working, Cypress will exit without explanation,
        see ${issueUrl}
      Solution: Unset the DISPLAY variable and try again:
        DISPLAY= npx cypress run ...
    `
    return false
  }
  debug('Cypress will spawn its own Xvfb')
  return true
}

Xvfb screen configuration from `cli/lib/exec/xvfb.ts:14-19`:

const xvfbOptions: any = {
  displayNum: process.env.XVFB_DISPLAY_NUM,
  timeout: 30000, // milliseconds
  // need to explicitly define screen otherwise electron will crash
  // https://github.com/cypress-io/cypress/issues/6184
  xvfb_args: ['-screen', '0', '1280x1024x24'],
}

Electron sandbox requirement from `cli/lib/tasks/verify.ts:372-383`:

const isLinuxLike = (): boolean => os.platform() !== 'win32'

/**
 * Returns true if running on a system where Electron needs "--no-sandbox" flag.
 * @see https://crbug.com/638180
 *
 * On Debian we had problems running in sandbox even for non-root users.
 * @see https://github.com/cypress-io/cypress/issues/5434
 * Seems there is a lot of discussion around this issue among Electron users
 * @see https://github.com/electron/electron/issues/17972
*/
export const needsSandbox = (): boolean => isLinuxLike()

Display error retry logic from `cli/lib/tasks/verify.ts:154-177`:

const userFriendlySpawn = async (linuxWithDisplayEnv: boolean): Promise<void> => {
  try {
    await spawn(linuxWithDisplayEnv)
  } catch (err: any) {
    if (err.code === 'INVALID_SMOKE_TEST_DISPLAY_ERROR') {
      return spawnInXvfb(linuxWithDisplayEnv)
    }
    throw err
  }
}

Common Errors

Error Message	Cause	Solution
`FATAL:setuid_sandbox_host.cc`	Ubuntu 24.04+ user namespace restrictions	sudo tee /etc/sysctl.d/60-apparmor-namespace.conf && sudo sysctl --system`
`missingXvfb` error	Xvfb not installed and no DISPLAY set	`sudo apt-get install -y xvfb`
`nonZeroExitCodeXvfb`	Xvfb failed to start	Check if another Xvfb instance is running; verify `xvfb` package is installed
Cypress exits without explanation	DISPLAY set but X11 server not working	Unset DISPLAY: `DISPLAY= npx cypress run ...`
`missingDependency` during verify	Missing system libraries (GTK, NSS, etc.)	Install all Cypress system dependencies (see Quick Install)
`invalidSmokeTestDisplayError`	Broken GTK display during verification	Cypress will auto-retry with Xvfb; if persistent, unset DISPLAY

Compatibility Notes

macOS/Windows: This environment is Linux-specific. macOS and Windows handle display rendering natively without Xvfb.
Docker: Most Cypress Docker images include Xvfb and all system dependencies pre-installed. Use `cypress/browsers` images for CI.
Ubuntu 24.04+: The AppArmor user namespace restriction is a known breaking change. The `FATAL:setuid_sandbox_host.cc` error is the primary symptom.
--no-sandbox: Applied automatically on all non-Windows platforms (Linux and macOS). This is due to longstanding Electron/Chromium sandbox issues on these platforms.
DISPLAY variable gotcha: If DISPLAY is set but points to a non-working X11 server, Cypress will exit silently. This is a known issue (GitHub #4034).
Docker performance: Running tests in Docker may be slower due to resource constraints. Ports 5566 and 5567 are available for debugger attachment when using `docker compose run --service-port dev`.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment