{"id":3785,"library":"pyvirtualdisplay","title":"PyVirtualDisplay","description":"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.","status":"active","version":"3.0","language":"en","source_language":"en","source_url":"https://github.com/ponty/pyvirtualdisplay","tags":["GUI automation","headless browser","testing","X server","virtual display","CI/CD"],"install":[{"cmd":"pip install pyvirtualdisplay","lang":"bash","label":"Install PyVirtualDisplay"},{"cmd":"sudo apt-get install xvfb xserver-xephyr tigervnc-standalone-server x11-utils","lang":"bash","label":"Install X server backends (Ubuntu/Debian example)"},{"cmd":"brew install xquartz","lang":"bash","label":"Install XQuartz for MacOS (for Xvfb/Xephyr)"}],"dependencies":[{"reason":"Requires Python 3.6 or later.","package":"python","optional":false},{"reason":"One of these X server programs must be installed on the underlying operating system.","package":"Xvfb, Xephyr, or Xvnc","optional":false},{"reason":"Optional, for functionality in the `smartdisplay` submodule (e.g., screenshots and autocrop).","package":"Pillow","optional":true},{"reason":"Optional, for running some examples.","package":"EasyProcess","optional":true},{"reason":"Optional, if `use_xauth=True` is passed to the Display constructor for Xauthority file generation.","package":"xauth","optional":true}],"imports":[{"symbol":"Display","correct":"from pyvirtualdisplay import Display"},{"note":"Used for advanced features like automated screenshots with cropping.","symbol":"SmartDisplay","correct":"from pyvirtualdisplay.smartdisplay import SmartDisplay"}],"quickstart":{"code":"from pyvirtualdisplay import Display\nimport time\nimport os\n\n# Ensure Xvfb or a similar X server is installed on the OS\n# Example for Linux: sudo apt-get install xvfb\n\n# For thread-safe operations in concurrent environments, use manage_global_env=False\n# and explicitly set os.environ['DISPLAY'] if needed within the thread/process.\n# For simple, single-threaded use, the default is often sufficient.\nwith Display(visible=0, size=(1920, 1080), backend='xvfb') as disp:\n    print(f\"Virtual display started on: {os.environ.get('DISPLAY')}\")\n    print(f\"Is display alive: {disp.is_alive()}\")\n    # Simulate doing some work that requires a display\n    time.sleep(2)\n    print(f\"Work done within virtual display. Is display still alive: {disp.is_alive()}\")\n\nprint(f\"Virtual display stopped. Is display alive: {disp.is_alive()}\")\n# os.environ['DISPLAY'] is restored to its original value after context manager exits","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"1.0 and later"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"0.2.2 and later"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}