---
id: xvfbwrapper
version: "0.2.29"
license: MIT
license_treatment: permissive
maintenance: active
---

# xvfbwrapper — Manage headless displays with Xvfb (X virtual framebuffer)

License: permissive · Maintenance: active · Downloads: 831.2K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 831.2K/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

headless display X11, xvfb virtual framebuffer, GUI testing without display, headless selenium testing, X virtual display management, headless browser automation, xvfb wrapper python, headless-testing, x11-display, gui-automation

[View on SkillFed](https://skillfed.io/packages/xvfbwrapper) · [View on PyPI](https://pypi.org/project/xvfbwrapper/)