Xvfbwrapper

0.2.23 · active · verified Mon Apr 13

xvfbwrapper is a Python library for controlling X11 virtual displays with Xvfb (X virtual framebuffer). Xvfb is a display server implementing the X11 protocol that runs entirely in memory, without requiring a physical screen or input devices. This enables GUI applications designed for X Windows to execute on headless systems, which is particularly useful for automated testing. The current version is 0.2.23, and it is actively maintained.

Warnings

gotcha The `Xvfb` binary must be installed on your system. `xvfbwrapper` is a Python wrapper, not a complete Xvfb distribution. Failure to install the system-level `Xvfb` will result in runtime errors.
Fix: Install Xvfb on your operating system (e.g., `sudo apt-get install xvfb` on Debian/Ubuntu, `yum install xorg-x11-server-Xvfb` on Red Hat/CentOS).
gotcha Always use `Xvfb` as a context manager (`with Xvfb(): ...`) or ensure `Xvfb().start()` is paired with `Xvfb().stop()` in a `try/finally` block. Failing to stop the display can leave behind temporary lock files in `/tmp`, leading to resource leaks and potential issues with future Xvfb sessions.
Fix: Adopt the context manager pattern: `with Xvfb(): # your code` or `xvfb = Xvfb(); xvfb.start(); try: # your code finally: xvfb.stop()`.
gotcha When running GUI toolkits in a Wayland session, they may default to the Wayland backend instead of connecting to Xvfb. This can lead to applications not rendering correctly on the virtual display.
Fix: Set `set_xdg_session_type=True` when initializing `Xvfb` (e.g., `Xvfb(set_xdg_session_type=True)`) or explicitly set `os.environ["XDG_SESSION_TYPE"] = "x11"` before launching your GUI application.
gotcha Prior to version 0.2.20 (released early 2025), if the `DISPLAY` environment variable was set to an empty string, `xvfbwrapper` could fail with an exception. This issue has since been resolved.
Fix: Upgrade to `xvfbwrapper` version 0.2.20 or newer. If upgrading isn't possible, ensure the `DISPLAY` environment variable is either unset or contains a valid display string, not an empty one.

Install

pip install xvfbwrapper Install from PyPI

Imports

Xvfb
```
from xvfbwrapper import Xvfb
```

Quickstart

This quickstart demonstrates the recommended way to use `xvfbwrapper` with a context manager. It automatically starts and stops the Xvfb display, ensuring proper cleanup. The `DISPLAY` environment variable is set for child processes within the `with` block. Note that the system-level `Xvfb` package must be installed first.

import os
from xvfbwrapper import Xvfb

# Ensure Xvfb is available on your system (e.g., sudo apt-get install xvfb)

# Using Xvfb as a context manager is recommended for safe cleanup
with Xvfb(width=1280, height=720, colordepth=24):
    print("Xvfb virtual display started.")
    print(f"DISPLAY environment variable is: {os.environ.get('DISPLAY')}")
    # Your application that needs a display runs here
    # Example: launch a headless browser or GUI application
    # The display will be stopped automatically when exiting the 'with' block
    print("Application finished, Xvfb will stop.")

print("Xvfb virtual display stopped.")

view raw JSON →