{"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":"python","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,"search_vec":"'0.2.23':63 'activ':67 'applic':42 'autom':57 'control':8 'current':60 'design':43 'devic':38 'display':11,20,75 'enabl':40 'entir':28 'execut':48 'framebuff':16 'gui':41,73 'headless':50,69 'implement':22 'input':37 'librari':6 'maintain':68 'memori':30 'particular':54 'physic':34 'protocol':25 'python':5 'requir':32 'run':27 'screen':35 'server':21 'system':51 'test':58,70 'use':55 'version':61 'virtual':10,15,74 'window':46 'without':31 'x':14,45 'x11':9,24,71 'xvfb':13,17,72 'xvfbwrapper':1,2","created_at":"2026-04-14T01:38:50.632254+00:00","updated_at":"2026-04-17T00:59:33.412137+00:00","problems":[{"fix":"Install the package using pip: `pip install xvfbwrapper`","cause":"The 'xvfbwrapper' Python package is not installed in the current environment.","error":"ModuleNotFoundError: No module named 'xvfbwrapper'"},{"fix":"Use the correct import statement: `from xvfbwrapper import Xvfb`","cause":"The 'Xvfb' class was not correctly imported from the 'xvfbwrapper' module, likely due to using `import xvfbwrapper` instead of `from xvfbwrapper import Xvfb`.","error":"NameError: name 'Xvfb' is not defined"},{"fix":"Install 'Xvfb' using your system's package manager (e.g., `sudo apt-get install xvfb` on Debian/Ubuntu, `sudo yum install xorg-x11-server-Xvfb` on RHEL/CentOS).","cause":"The 'Xvfb' executable is not installed on the system, or it is not found in the system's PATH environment variable.","error":"OSError: [Errno 2] No such file or directory: 'Xvfb'"},{"fix":"Increase the timeout when initializing Xvfb (e.g., `Xvfb(timeout=30)`) or investigate system-level issues preventing Xvfb from starting correctly, such as available display numbers or hardware resources.","cause":"Xvfb failed to start within the default timeout period, possibly due to system resource issues, an invalid display number, or other problems preventing the X server from becoming ready.","error":"RuntimeError: Xvfb did not start within 10 seconds"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.2.29","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/cgoldberg/xvfbwrapper","docs":null,"changelog":null,"pypi":"https://pypi.org/project/xvfbwrapper/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}