sbvirtualdisplay

library1.4.0pypypi✓ verified 28d ago

sbvirtualdisplay (current version 1.4.0) is a Python library that provides a customized virtual display for headless browser automation, primarily designed for use with SeleniumBase. It functions as a wrapper around Xvfb, Xephyr, or Xvnc programs, enabling browser tests to run in environments without a physical display server, which is particularly useful for Linux backend servers. The library is actively maintained with a steady release cadence.

testing devops

pip install sbvirtualdisplay

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · SBVIRTUALDISPLAY

sbvirtualdisplay

testingpythonv1.4.0

Install

1.6s avg

Import

51ms

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 v1.4.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.052s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.050s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

Display

✓ from sbvirtualdisplay import Display

Initialize a virtual display with specified visibility and resolution, then execute browser automation code within its context. The context manager ensures the display is properly started and stopped.

from sbvirtualdisplay import Display # Example usage with context manager (recommended) with Display(visible=0, size=(1440, 1880)): # Code to run browser tests in a headless environment print("Virtual display is active, running tests...") # Example: driver = webdriver.Chrome(options=options) # driver.get("http://example.com") # ... print("Virtual display is stopped.") # Alternative usage with explicit start/stop display = Display(visible=0, size=(1440, 1880)) try: display.start() print("Virtual display started, running tests...") # Example: driver = webdriver.Firefox(options=options) # driver.get("http://example.com") # ... finally: display.stop() print("Virtual display stopped.")

Debug

Known issues

breakingSupport for Python 3.7 was dropped in version 1.4.0. Projects requiring Python 3.7 or older must use an earlier version of sbvirtualdisplay.

fix

Upgrade to Python 3.8 or newer, or pin sbvirtualdisplay to <1.4.0 if Python 3.7 is required.

affects: >=1.4.0

breakingSupport for Python 2.7 and Python 3.6 was dropped in version 1.3.0. The minimum supported Python version became 3.7 (and later 3.8 in 1.4.0).

fix

Upgrade to Python 3.8 or newer. If older Python versions are necessary, use sbvirtualdisplay <1.3.0.

affects: >=1.3.0

gotchaThis library is primarily designed for Linux environments due to its reliance on the X Window System (via Xvfb, Xephyr, or Xvnc). It is not intended for use on Windows or macOS.

fix

Ensure that a compatible X server (like Xvfb) is installed and available on the Linux system where sbvirtualdisplay is used. For macOS/Windows, consider native headless browser modes (e.g., Chrome/Firefox `--headless=new`) or other platform-specific solutions.

affects: all

gotchaThe underlying X server (e.g., Xvfb) must be installed on the system where sbvirtualdisplay runs. This library is a Python wrapper and does not install the X server itself.

fix

Install `Xvfb` (or `Xephyr`/`Xvnc`) via your system's package manager (e.g., `sudo apt-get install xvfb` on Ubuntu) before using `sbvirtualdisplay`.

affects: all

Errors

Common errors & fixes

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

The underlying Xvfb display server program, which sbvirtualdisplay uses as a backend, is not installed or not found in your system's PATH.

fix

Install Xvfb using your system's package manager. For Debian/Ubuntu: `sudo apt-get install xvfb`. For CentOS/RHEL: `sudo yum install xorg-x11-server-Xvfb`.

pyvirtualdisplay.abstractdisplay.XStartError: X server did not start.

The virtual display server (e.g., Xvfb) failed to launch. This often happens because the specified display number is already in use, or there are other environmental issues preventing the X server from starting.

fix

Ensure all previous virtual display processes are terminated. If manually specifying `os_display_number`, try removing it to let sbvirtualdisplay find a free display, or choose a higher, unused number (e.g., `display = Display(visible=0, os_display_number=100)`).

ValueError: Invalid backend '...' (e.g., 'nonexistent')

The specified `backend` for the virtual display is not recognized or supported by sbvirtualdisplay. Valid backends are typically `'xvfb'`, `'xephyr'`, or `'xvnc'`.

fix

Use one of the supported backend names: `'xvfb'`, `'xephyr'`, or `'xvnc'`. For example, `Display(backend='xvfb', ...)`. Ensure the chosen backend's executable is also installed on your system.

Upgrade

Version history

1.4.0latest on PyPI · released Dec 16, 2024

Audit

Dependencies

pyvirtualdisplayrequiredThis library is a customized wrapper for pyvirtualdisplay, relying on its core functionality to manage virtual displays.

Xvfboptionalsbvirtualdisplay (and its base, pyvirtualdisplay) requires an X server like Xvfb (or Xephyr/Xvnc) to be installed on the system to function.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/mdmintz/sbVirtualDisplay ↗

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

changeloghttps://github.com/mdmintz/sbVirtualDisplay/releases ↗