xvfb-run

Run the specified command in a virtual X server

$ xvfb-run [command]

$ xvfb-run [[-a|--auto-servernum]] [command]

$ xvfb-run [[-s|--server-args]] "[-screen 0 1024x768x24]" [command]

xvfb-run [options] command [args ...]
xvfb-run [options] -

-a, --auto-display
    Automatically select an available display number for Xvfb.

-e FILE, --error-file=FILE
    Redirects Xvfb's standard error output to the specified FILE.

-f FILE, --auth-file=FILE
    Specifies an X authority file (e.g., for xauth) to store connection credentials.

-h, --help
    Displays a comprehensive help message and exits.

-l, --listen-tcp
    Enables TCP connections to the Xvfb server, generally less secure and not recommended for typical use.

-n DISPLAY, --server-num=DISPLAY
    Sets the specific X display number (e.g., `99`) for Xvfb to use.

-o OPTIONS, --server-options=OPTIONS
    Passes additional, raw OPTIONS directly to the Xvfb server command line.

-p PROTOCOL, --xauth-protocol=PROTOCOL
    Specifies the X authority protocol to use (default is `MIT-MAGIC-COOKIE-1`).

-s SIZE, --server-display=SIZE
    Defines the screen resolution and color depth for Xvfb, e.g., `1024x768x24`.

-w DELAY, --wait=DELAY
    Waits for up to DELAY seconds for the Xvfb server to successfully start.

-X, --no-xauth
    Disables the use of X authority for client connections, reducing security.

-P PIDFILE, --pidfile=PIDFILE
    Writes the Process ID (PID) of the Xvfb server to the specified PIDFILE.

-d, --debug
    Enables debug mode, providing more verbose output from xvfb-run itself.

-V, --version
    Displays the xvfb-run version information and exits.

xvfb-run is a utility script that automates the process of starting the Xvfb (X virtual framebuffer) server, setting up the DISPLAY environment variable, executing a specified graphical application, and then safely shutting down Xvfb upon the application's exit.

This utility is invaluable for scenarios where a graphical environment is required but a physical display is unavailable or undesirable, such as on headless servers, for automated UI testing (e.g., with Selenium or Cypress), or for rendering graphical content into images (e.g., using wkhtmltopdf). It allows applications that inherently depend on an X server to run seamlessly without a visible desktop, making them suitable for batch processing or continuous integration/delivery pipelines. xvfb-run handles the complex setup of Xvfb's command-line arguments and display management, abstracting away the underlying details for the user.

• xvfb-run consumes system resources (CPU, memory) just like a regular X server, albeit without a physical display.
• Running Xvfb with root privileges is generally discouraged unless strictly necessary due to security implications, especially when using options like `--listen-tcp` or `--no-xauth`.
• Applications running under xvfb-run cannot interact with a physical display or user input.
• Troubleshooting can be challenging if the X client fails silently; checking Xvfb's stderr (e.g., with `-e`) is often helpful.
• The DISPLAY variable is automatically set by xvfb-run; manually setting it beforehand can lead to conflicts.

xvfb-run automatically assigns an available display number (e.g., `:99`) and sets the DISPLAY environment variable for the command it executes. This allows the X client to find and connect to the Xvfb server.

By default, xvfb-run uses xauth to create a magic cookie, ensuring that only authorized clients can connect to the Xvfb server, enhancing security, especially when Xvfb might be accessible from other hosts (though `--listen-tcp` is rarely used).

A common use case involves running a headless web browser for automated testing or screenshot generation:
xvfb-run \
  --server-args="-screen 0 1024x768x24" \
  firefox --headless -screenshot example.png example.com
This example demonstrates running a headless Firefox instance within Xvfb to take a screenshot of a webpage with a specified screen resolution.

The Xvfb (X virtual framebuffer) server itself has been a part of the X Window System since X11R6 (around 1994), primarily developed for testing X server implementations and for applications needing an X server without a graphics card. xvfb-run emerged later as a convenience wrapper script, simplifying the complex invocation of Xvfb by handling display number allocation, DISPLAY environment variable setup, and xauth cookie management.

Its development was driven by the increasing need for automated testing of GUI applications and for server-side processing of graphical content in headless environments, allowing X-dependent software to run seamlessly in CI/CD pipelines or cloud infrastructure without manual configuration of a virtual display.

Xvfb(1), xauth(1), X(7), DISPLAY(7), startx(1), xinit(1)