xvfbwrapper

library0.2.29pypypi✓ verified 21d ago

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.

testing devops

pip install xvfbwrapper

github ↗package ↗

INSTALL

IMPORT

SIG · XVFBWRAPPER

xvfbwrapper

testingpythonv0.2.29

Install

1.5s avg

Import

44ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.2.29 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.046s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.042s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Xvfb

✓ from xvfbwrapper import Xvfb

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.")

Debug

Known issues

gotchaThe `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).

affects: All versions

gotchaAlways 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()`.

affects: All versions

gotchaWhen 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.

affects: All versions

gotchaPrior 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.

affects: < 0.2.20

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'xvfbwrapper'

The 'xvfbwrapper' Python package is not installed in the current environment.

fix

Install the package using pip: `pip install xvfbwrapper`

NameError: name 'Xvfb' is not defined

The 'Xvfb' class was not correctly imported from the 'xvfbwrapper' module, likely due to using `import xvfbwrapper` instead of `from xvfbwrapper import Xvfb`.

fix

Use the correct import statement: `from xvfbwrapper import Xvfb`

OSError: [Errno 2] No such file or directory: 'Xvfb'

The 'Xvfb' executable is not installed on the system, or it is not found in the system's PATH environment variable.

fix

Install 'Xvfb' using your system's package manager (e.g., `sudo apt-get install xvfb` on Debian/Ubuntu, `sudo yum install xorg-x11-server-Xvfb` on RHEL/CentOS).

RuntimeError: Xvfb did not start within 10 seconds

Xvfb failed to start within the default timeout period, possibly due to system resource issues, an invalid display number, or other problems preventing the X server from becoming ready.

fix

Increase the timeout when initializing Xvfb (e.g., `Xvfb(timeout=30)`) or investigate system-level issues preventing Xvfb from starting correctly, such as available display numbers or hardware resources.

Upgrade

Version history

0.2.29latest on PyPI · released Jul 23, 2026

Audit

Dependencies

XvfbrequiredRequired system-level X virtual framebuffer server. Must be installed separately (e.g., `sudo apt-get install xvfb` on Debian/Ubuntu, `yum install xorg-x11-server-Xvfb` on Red Hat/CentOS).

X Window SystemrequiredUnderlying system environment for Xvfb to function.

fcntlrequiredPython's `fcntl` module is used for file locking; required on non-Windows systems.

Agent activity

26 hits · last 30 days

node

Resources

githubhttps://github.com/cgoldberg/xvfbwrapper ↗

packagehttps://pypi.org/project/xvfbwrapper/ ↗