PyVirtualDisplay

Warnings

• breaking Major 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.
• gotcha PyVirtualDisplay 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.
• gotcha When 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.
• gotcha Starting 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`.
• gotcha PyVirtualDisplay 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).

Install

• pip install pyvirtualdisplay Install PyVirtualDisplay
• sudo apt-get install xvfb xserver-xephyr tigervnc-standalone-server x11-utils Install X server backends (Ubuntu/Debian example)
• brew install xquartz Install XQuartz for MacOS (for Xvfb/Xephyr)

Imports

• Display

  from pyvirtualdisplay import Display

• SmartDisplay

  from pyvirtualdisplay.smartdisplay import SmartDisplay

  Used for advanced features like automated screenshots with cropping.

Quickstart

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