Cypress "Your system is missing the dependency: Xvfb" in CI

Cypress on Linux drives an Electron browser that needs an X display. On a headless runner there is no real display, so Cypress expects Xvfb (a virtual framebuffer) to be installed. When it is missing, Cypress stops and names Xvfb directly.

What this error means

Cypress fails with "Your system is missing the dependency: Xvfb" and "Install Xvfb and run Cypress again" before any spec executes.

Cypress

Your system is missing the dependency: Xvfb

Install Xvfb and run Cypress again.

Read our documentation on dependencies for more information:
  https://on.cypress.io/required-dependencies

Common causes

Xvfb is not installed on the runner

A slim Linux image has no xvfb package, so Cypress cannot start a virtual display for the browser.

A custom image built without the X stack

A hand-rolled CI image omitted Xvfb and its X11 dependencies to stay small.

How to fix it

Install Xvfb before running Cypress

Add the xvfb package and the X auth helper to the runner.

Terminal

sudo apt-get update
sudo apt-get install -y xvfb libgtk-3-0 libgbm1 libnss3 libasound2

Use a Cypress image that includes Xvfb

The maintained images bundle Xvfb so no manual install is needed.

.github/workflows/ci.yml

container:
  image: cypress/browsers:node-20.11.0-chrome-124

How to prevent it

Install xvfb on any custom Linux CI image that runs Cypress.
Prefer the official Cypress images, which include Xvfb.
Keep the X11 helper packages (xauth) alongside Xvfb.