PyVirtualDisplay

What it is and what it does

PyVirtualDisplay is a Python wrapper that manages virtual X11 display servers (Xvfb, Xephyr, Xvnc) on Linux. It lets you run GUI applications and capture their output without a physical display or graphical environment. The package handles display lifecycle (start/stop), environment variable management, and optional screenshot capture via its SmartDisplay submodule.

Typical use is in CI/CD pipelines, automated testing, and server environments where you need to run GUI tools headlessly. It requires the underlying X server backend (Xvfb, Xephyr, or Xvnc) to be installed on the system separately; PyVirtualDisplay only wraps and controls them. The context-manager API makes cleanup automatic.

Use it for:

• Run GUI tests in CI/CD without a display server, capturing pass/fail via virtual display.
• Automate screenshots of X11 applications running on a headless server.
• Test applications at specific resolutions or color depths by configuring virtual display parameters.
• Expose a GUI application via VNC by running it on a virtual Xvnc backend.
• Run multiple nested X servers concurrently for complex testing scenarios.

Worth the install?

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

Wraps Xvfb, Xephyr, and Xvnc to create virtual X11 displays for headless GUI testing, automation, and screenshots on Linux systems.

Yes, if you need headless X11 GUI automation on Linux and can accept dormant maintenance. The package is stable, has no dependencies, and works reliably for its core use case. Install the underlying X server backend (xvfb, xephyr, or tigervnc-server) separately on your system first. Not suitable for macOS or Windows.

Install

pyvirtualdisplay on PyPI

pip install pyvirtualdisplay

uv add pyvirtualdisplay

poetry add pyvirtualdisplay

Installing PyVirtualDisplay

Before you install

Low install friction with no runtime dependencies. Maintenance is dormant—last release was in 2022 and no commits since February 2024—but the package is stable and widely used (780 GitHub stars, top 5000 on PyPI).

License in practice

BSD license is permissive; you can use this in commercial and proprietary projects with minimal restrictions.

Quickstart

from pyvirtualdisplay import Display

with Display(visible=False, size=(100, 60)) as disp:
    # Run GUI applications here
    print(disp.is_alive())  # True
# Display automatically stopped

Requires Xvfb, Xephyr, or Xvnc to be installed on the system (e.g., `sudo apt-get install xvfb` on Ubuntu). Only works on Linux with X11; not compatible with Windows or macOS.

Verify before relying

• Whether the package works reliably with Python 3.12 (description mentions it but classifiers only list through 3.11).
• Current status of thread-safety guarantees and whether manage_global_env=False is production-ready.
• Whether dormant maintenance poses risk for future X11 ecosystem changes or Python version incompatibilities.

Package facts

Evidence: PyVirtualDisplay-3.0-py3-none-any.whl

Keywords: Xvfb, Xephyr, X, wrapper

Tags

More Testing packages