xvfbwrapper

What it is and what it does

xvfbwrapper is a Python wrapper around Xvfb (X virtual framebuffer), a display server that runs in memory without requiring physical hardware. It lets you start, configure, and stop virtual X11 displays programmatically, making it possible to run GUI applications and browser automation on headless servers. The package provides a simple `Xvfb` class that handles display lifecycle management, supports context managers for clean resource cleanup, and allows fine-grained control over display geometry, display number, and Xvfb command-line options.

The primary use case is automated testing of GUI applications—particularly headless Selenium WebDriver tests running Chrome or Firefox on CI/CD systems. It also supports multithreaded execution with isolated environments, environment variable configuration (including Wayland compatibility via `XDG_SESSION_TYPE`), and custom Xvfb arguments. Since its first release in 2012, it has remained a stable, low-dependency tool for developers who need to render X11 applications without a display.

Use it for:

• Run headless Selenium WebDriver tests for browser automation on CI/CD pipelines without a display server.
• Test GUI applications written in GTK, Qt, or other X11 toolkits in automated test suites on Linux servers.
• Launch multiple isolated virtual displays in parallel threads or processes for concurrent GUI testing.
• Render screenshots or perform visual regression testing on web applications in a headless environment.
• Execute X11-based command-line tools that require a display (e.g., image processing, rendering utilities) on servers.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Manages headless X11 virtual displays using Xvfb, allowing GUI applications to run without a physical display on Linux/Unix systems.

Yes. xvfbwrapper is actively maintained, has no runtime dependencies, carries a permissive MIT license, and solves a specific, well-defined problem for headless GUI testing on Linux/Unix. Install it if you need to run X11 applications or browser automation tests without a physical display. The only prerequisite is the system-level Xvfb package, which is standard on most Linux distributions.

Install

xvfbwrapper on PyPI

pip install xvfbwrapper

uv add xvfbwrapper

poetry add xvfbwrapper

Installing xvfbwrapper

Before you install

Low friction install with no runtime dependencies. Actively maintained since 2012, with recent release (22 days old) and active repository. Supports current Python versions (3.10–3.14). Requires system-level Xvfb package and X Window System on Linux/Unix.

License in practice

MIT license (permissive) places no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart

pip install xvfbwrapper

from xvfbwrapper import Xvfb

with Xvfb():
    # launch GUI applications here

Requires Xvfb system package installed (e.g. `apt-get install xvfb`), X Window System, and a non-Windows OS with fcntl support (Linux/Unix).

Verify before relying

• Whether the package works reliably with all advertised Python versions (3.10–3.14) in production environments.
• Performance characteristics when managing multiple simultaneous Xvfb displays under load.

Package facts

Evidence: xvfbwrapper-0.2.29-py3-none-any.whl

Keywords: Xvfb, headless, display, X11, X Window System

Tags

More Python Modules packages