{"id":5554,"library":"xvfbwrapper","title":"Xvfbwrapper","description":"xvfbwrapper is a Python library for controlling X11 virtual displays with Xvfb (X virtual framebuffer). Xvfb is a display server implementing the X11 protocol that runs entirely in memory, without requiring a physical screen or input devices. This enables GUI applications designed for X Windows to execute on headless systems, which is particularly useful for automated testing. The current version is 0.2.23, and it is actively maintained.","status":"active","version":"0.2.23","language":"en","source_language":"en","source_url":"https://github.com/cgoldberg/xvfbwrapper","tags":["headless","testing","X11","Xvfb","GUI","virtual display"],"install":[{"cmd":"pip install xvfbwrapper","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Required system-level X virtual framebuffer server. Must be installed separately (e.g., `sudo apt-get install xvfb` on Debian/Ubuntu, `yum install xorg-x11-server-Xvfb` on Red Hat/CentOS).","package":"Xvfb","optional":false},{"reason":"Underlying system environment for Xvfb to function.","package":"X Window System","optional":false},{"reason":"Python's `fcntl` module is used for file locking; required on non-Windows systems.","package":"fcntl","optional":false}],"imports":[{"symbol":"Xvfb","correct":"from xvfbwrapper import Xvfb"}],"quickstart":{"code":"import os\nfrom xvfbwrapper import Xvfb\n\n# Ensure Xvfb is available on your system (e.g., sudo apt-get install xvfb)\n\n# Using Xvfb as a context manager is recommended for safe cleanup\nwith Xvfb(width=1280, height=720, colordepth=24):\n    print(\"Xvfb virtual display started.\")\n    print(f\"DISPLAY environment variable is: {os.environ.get('DISPLAY')}\")\n    # Your application that needs a display runs here\n    # Example: launch a headless browser or GUI application\n    # The display will be stopped automatically when exiting the 'with' block\n    print(\"Application finished, Xvfb will stop.\")\n\nprint(\"Xvfb virtual display stopped.\")","lang":"python","description":"This quickstart demonstrates the recommended way to use `xvfbwrapper` with a context manager. It automatically starts and stops the Xvfb display, ensuring proper cleanup. The `DISPLAY` environment variable is set for child processes within the `with` block. Note that the system-level `Xvfb` package must be installed first."},"warnings":[{"fix":"Install Xvfb on your operating system (e.g., `sudo apt-get install xvfb` on Debian/Ubuntu, `yum install xorg-x11-server-Xvfb` on Red Hat/CentOS).","message":"The `Xvfb` binary must be installed on your system. `xvfbwrapper` is a Python wrapper, not a complete Xvfb distribution. Failure to install the system-level `Xvfb` will result in runtime errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Adopt the context manager pattern: `with Xvfb(): # your code` or `xvfb = Xvfb(); xvfb.start(); try: # your code finally: xvfb.stop()`.","message":"Always use `Xvfb` as a context manager (`with Xvfb(): ...`) or ensure `Xvfb().start()` is paired with `Xvfb().stop()` in a `try/finally` block. Failing to stop the display can leave behind temporary lock files in `/tmp`, leading to resource leaks and potential issues with future Xvfb sessions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set `set_xdg_session_type=True` when initializing `Xvfb` (e.g., `Xvfb(set_xdg_session_type=True)`) or explicitly set `os.environ[\"XDG_SESSION_TYPE\"] = \"x11\"` before launching your GUI application.","message":"When running GUI toolkits in a Wayland session, they may default to the Wayland backend instead of connecting to Xvfb. This can lead to applications not rendering correctly on the virtual display.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `xvfbwrapper` version 0.2.20 or newer. If upgrading isn't possible, ensure the `DISPLAY` environment variable is either unset or contains a valid display string, not an empty one.","message":"Prior to version 0.2.20 (released early 2025), if the `DISPLAY` environment variable was set to an empty string, `xvfbwrapper` could fail with an exception. This issue has since been resolved.","severity":"gotcha","affected_versions":"< 0.2.20"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}