---
id: sbvirtualdisplay
version: "1.4.0"
license: MIT
license_treatment: permissive
maintenance: dormant
---

# sbvirtualdisplay — A customized pyvirtualdisplay for SeleniumBase.

License: permissive · Maintenance: dormant · Downloads: 754.8K/mo

## What it is and what it does

sbVirtualDisplay is a thin wrapper around PyVirtualDisplay customized for SeleniumBase test automation. It creates a virtual X11 display on headless systems, allowing browser tests to run in a graphical environment even when no physical display is present. This is useful when browser headless modes are insufficient—for instance, Chrome's headless mode does not support extensions, so if you need to test with extensions on a headless Linux machine, a virtual display lets you run the browser in normal (non-headless) mode.

The package is pure Python with no runtime dependencies, making installation straightforward. It supports Python 3.8 through 3.13 and works on Linux, macOS, and Windows (though Xvfb, the underlying X11 virtual framebuffer, is the critical system requirement). Maintenance is dormant but stable; the codebase is marked Production/Stable.

Use it for:

- Running Selenium tests with Chrome extensions on a headless Linux CI/CD server where headless mode is not an option.
- Automating browser interactions in a containerized environment without a display manager.
- Testing browser UI behavior that requires a full graphical context rather than a headless rendering mode.
- Integrating with SeleniumBase test suites that need virtual display support for complex automation scenarios.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides a virtual display wrapper for running browser automation tests in headless environments, particularly when browser headless modes are insufficient (e.g., for Chrome extensions).

Yes, if you need to run browser tests with extensions or require a full graphical context on a headless system and Xvfb is available. The low install friction, permissive license, and stable codebase make it a safe choice for this specific use case. Not necessary if your browser's native headless mode meets your needs or if you lack Xvfb on your target platform.

## Install

pip install sbvirtualdisplay
uv add sbvirtualdisplay
poetry add sbvirtualdisplay

## Installing sbvirtualdisplay

Before you install: Low friction: pure Python wheel with no runtime dependencies. Maintenance is dormant, though the repository remains active with a recent commit on 2024-12-16. Suitable for stable, established use cases.

License in practice: MIT license (permissive) places no restrictions on use, modification, or distribution. Safe for commercial and proprietary projects.

Quickstart:

from sbvirtualdisplay import Display

display = Display(visible=0, size=(1440, 1880))
display.start()
# Run browser tests
display.stop()

# Or as context manager:
with Display(visible=0, size=(1440, 1880)):
    # Run browser tests

Xvfb must be installed on the system (typically available on Linux; not native to macOS or Windows).

Verify before relying:

- Whether Xvfb availability on macOS and Windows is practical or if this is Linux-only in practice despite classifier claims.
- Performance overhead of virtual display versus native headless browser modes in typical test scenarios.

## Package facts

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

## Tags

headless browser testing linux, virtual display xvfb wrapper, selenium headless environment, chrome extensions headless mode, browser automation without display, xvfb python wrapper, headless test runner, headless-testing, xvfb, browser-automation

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