pyvirtualdisplay

library3.0pypypi✓ verified 25d ago

PyVirtualDisplay is a Python wrapper for Xvfb, Xephyr, and Xvnc programs. It enables running graphical applications or tests in a headless environment by creating a virtual display, making it suitable for CI/CD pipelines and automated GUI testing. The library is currently at version 3.0 and supports Python versions 3.6 through 3.12.

testing devops

pip install pyvirtualdisplay

github ↗package ↗

INSTALL

IMPORT

SIG · PYVIRTUALDISPLAY

pyvirtualdisplay

testingpythonv3.0

Install

1.5s avg

Import

55ms

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 v3.0 · 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.056s · 17.9MB

glibc

py 3.10–3.95 runs

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

16MB installed

● package 16MB

Code

Verified usage

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

Display

✓ from pyvirtualdisplay import Display

SmartDisplay

✓ from pyvirtualdisplay.smartdisplay import SmartDisplay

Used for advanced features like automated screenshots with cropping.

This example demonstrates how to start and stop a virtual display using a context manager. It sets up an Xvfb backend with a specific resolution and ensures the display is properly managed. The `visible=0` argument ensures the display runs in headless mode.

from pyvirtualdisplay import Display import time import os # Ensure Xvfb or a similar X server is installed on the OS # Example for Linux: sudo apt-get install xvfb # For thread-safe operations in concurrent environments, use manage_global_env=False # and explicitly set os.environ['DISPLAY'] if needed within the thread/process. # For simple, single-threaded use, the default is often sufficient. with Display(visible=0, size=(1920, 1080), backend='xvfb') as disp: print(f"Virtual display started on: {os.environ.get('DISPLAY')}") print(f"Is display alive: {disp.is_alive()}") # Simulate doing some work that requires a display time.sleep(2) print(f"Work done within virtual display. Is display still alive: {disp.is_alive()}") print(f"Virtual display stopped. Is display alive: {disp.is_alive()}") # os.environ['DISPLAY'] is restored to its original value after context manager exits

Debug

Known issues

breakingMajor API changes occurred in version 1.0, breaking compatibility with previous versions (e.g., 0.2.5). Code written for older versions will likely fail with 1.x or later without modification.

fix

Review the official documentation and migrate code to use the updated API, particularly for `Display` constructor arguments and method calls. Pin `pyvirtualdisplay` to an older version (e.g., `==0.2.5`) if immediate migration is not possible.

affects: 1.0 and later

gotchaPyVirtualDisplay is a Python wrapper and *requires* an underlying X server program (like Xvfb, Xephyr, or Xvnc) to be installed on the operating system. Without it, you will encounter `FileNotFoundError` or `pyvirtualdisplay.abstractdisplay.XStartError`.

fix

Install the necessary X server packages on your system (e.g., `sudo apt-get install xvfb` on Debian/Ubuntu, `brew install xquartz` for Xvfb on MacOS). Ensure the chosen backend is in your system's PATH.

affects: All versions

gotchaWhen running PyVirtualDisplay in a multi-threaded or multi-process environment, the default behavior of modifying `os.environ['DISPLAY']` is not thread-safe. This can lead to race conditions or incorrect display assignments.

fix

Pass `manage_global_env=False` to the `Display` constructor. You will then need to manually manage the `DISPLAY` environment variable for each thread/process if it needs to interact with specific displays.

affects: All versions

gotchaStarting with version 0.2.2, a 10-second timeout (`XStartTimeoutError`) was introduced for the X server to start up. If the display takes longer to become ready, this error will be raised.

fix

Address the underlying cause of slow X server startup (e.g., system resources, misconfiguration). For older versions (pre-1.0), it might be possible to remove `xdpyinfo` (macOS workaround) or ensure proper permissions for `/tmp/.X11-unix`.

affects: 0.2.2 and later

gotchaPyVirtualDisplay does not run natively on Windows as it relies on the X Window System. Attempts to use it directly on Windows will result in `FileNotFoundError` for X server binaries.

fix

For Windows, use Windows Subsystem for Linux (WSL2) with an X server or utilize headless modes provided directly by web browsers (e.g., Chrome/Firefox headless).

affects: All versions

Errors

Common errors & fixes

Program 'Xvfb' not found in path. Please install it.

The backend program 'Xvfb', which pyvirtualdisplay uses to create a virtual display, is not installed on the system or is not accessible in the system's PATH.

fix

Install Xvfb on your operating system. For Debian/Ubuntu-based systems, use: `sudo apt-get install xvfb`

cannot connect to X server

An application trying to run graphically (e.g., a web browser for Selenium tests) is unable to find or connect to the virtual display created by pyvirtualdisplay.

fix

Ensure that the graphical application is started within the context of the active pyvirtualdisplay display, often by using a 'with' statement for the Display object, which automatically sets the DISPLAY environment variable.

pyvirtualdisplay.abstractdisplay.DisplayTimeoutError

The virtual display took longer than the default timeout (usually 10 seconds) to start up, possibly due to a slow system, heavy load, or issues with the backend program.

fix

Increase the `timeout` parameter when initializing the `Display` object to allow more time for the virtual display to start, e.g., `display = Display(visible=0, size=(800, 600), timeout=30)`.

ModuleNotFoundError: No module named 'virtualdisplay'

The library is being imported using the incorrect package name 'virtualdisplay' instead of the correct package name 'pyvirtualdisplay'.

fix

Change the import statement to `from pyvirtualdisplay import Display` or `import pyvirtualdisplay`.

Upgrade

Version history

3.0latest on PyPI · released Feb 13, 2022

Audit

Dependencies

pythonrequiredRequires Python 3.6 or later.

Xvfb, Xephyr, or XvncrequiredOne of these X server programs must be installed on the underlying operating system.

PillowoptionalOptional, for functionality in the `smartdisplay` submodule (e.g., screenshots and autocrop).

EasyProcessoptionalOptional, for running some examples.

xauthoptionalOptional, if `use_xauth=True` is passed to the Display constructor for Xauthority file generation.

Agent activity

27 hits · last 30 days

node

Resources

githubhttps://github.com/ponty/pyvirtualdisplay ↗

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