# xvfbwrapper
#### Manage headless displays with Xvfb (X virtual framebuffer)
- Copyright (c) 2012-2025 [Corey Goldberg][github-profile]
- Development: [GitHub][github-repo]
- Releases: [PyPI][pypi-home]
- License: [MIT][mit-license]
----
## About
`xvfbwrapper` is a Python module for controlling X11 virtual displays with Xvfb.
----
## What is Xvfb?
`Xvfb` (X virtual framebuffer) is a display server implementing the X11
display server protocol. It runs in memory and does not require a physical
display or input device. Only a network layer is necessary.
`Xvfb` allows GUI applications that use X Windows to run on a headless system.
----
## Installation
Official releases are published on [PyPI][pypi-home]:
```
pip install xvfbwrapper
```
----
## System Requirements
- Python 3.10+
- X Window System (or Xwayland)
- Xvfb (`sudo apt-get install xvfb`, `yum install xorg-x11-server-Xvfb`, etc)
- Support for locking with `fcntl` system call (non-Windows systems)
----
## Examples
#### Basic Usage:
Note: Always either wrap your usage of `Xvfb()` with try/finally, or use it as
a context manager to ensure the display is stopped. If you don't, you'll end up
with a bunch of junk in `/tmp` if errors occur.
```python
from xvfbwrapper import Xvfb
xvfb = Xvfb()
xvfb.start()
try:
# launch stuff inside virtual display here
finally:
xvfb.stop()
```
#### Usage as a context manager:
```python
from xvfbwrapper import Xvfb
with Xvfb():
# launch stuff inside virtual display here
# (Xvfb will stop when this block completes)
```
#### Specifying display geometry:
```python
from xvfbwrapper import Xvfb
xvfb = Xvfb(width=1280, height=720)
xvfb.start()
try:
# launch stuff inside virtual display here
finally:
xvfb.stop()
```
#### Specifying display number:
```python
from xvfbwrapper import Xvfb
xvfb = Xvfb(display=23)
xvfb.start()
# Xvfb is started with display :23
# see vdisplay.new_display
try:
# launch stuff inside virtual display here
finally:
xvfb.stop()
```
#### Multithreaded execution:
To run several Xvfb displays at the same time, you can use the `environ`
keyword when starting the `Xvfb` instances. This provides isolation between
processes or threads. Be sure to use the environment dictionary you initialize
`Xvfb` with in your subsequent calls. Also, if you wish to inherit your current
environment, you must use the copy method of `os.environ` and not simply
assign a new variable to `os.environ`:
```python
import os
from xvfbwrapper import Xvfb
isolated_environment1 = os.environ.copy()
xvfb1 = Xvfb(environ=isolated_environment1)
xvfb1.start()
isolated_environment2 = os.environ.copy()
xvfb2 = Xvfb(environ=isolated_environment2)
xvfb2.start()
try:
# launch stuff inside virtual displays here
finally:
xvfb1.stop()
xvfb2.stop()
```
#### Usage in testing - headless Selenium WebDriver tests:
This is a test using `selenium` and `xvfbwrapper` to run tests
on Chrome with a headless display. (see: [selenium docs][selenium-docs])
[selenium-docs]: https://www.selenium.dev/selenium/docs/api/py
```python
import os
import unittest
from selenium import webdriver
from xvfbwrapper import Xvfb
# force X11 in case we are running on a Wayland system
os.environ["XDG_SESSION_TYPE"] = "x11"
class TestPage(unittest.TestCase):
def setUp(self):
xvfb = Xvfb()
xvfb.start()
self.driver = webdriver.Chrome()
self.addCleanup(xvfb.stop)
self.addCleanup(self.driver.quit)
def test_selenium_homepage(self):
self.driver.get("https://www.selenium.dev")
self.assertIn("Selenium", self.driver.title)
if __name__ == "__main__":
unittest.main()
```
- virtual display is launched
- browser launches inside virtual display (headless)
- browser quits during cleanup
- virtual display stops during cleanup
----
## xvfbwrapper Issues
To report a bug or request a new feature, please open an issue on [GitHub][github-issues].
----
## xvfbwrapper Development
1. Fork the project repo on [GitHub][github-repo]
2. Clone the repo:
```
git clone https://github.com/<USERNAME>/xvfbwrapper.git
cd xvfbwrapper
```
3. Make changes and run the tests:
Create a virtual env and install required testing packages:
```
python -m venv venv
source ./venv/bin/activate
pip install --editable --group dev --group test .
```
Run all tests in the default Python environment::
```
pytest
```
Run all tests, linting, and type checking across all supported/installed
Python environments:
```
tox
```
4. Commit and push your changes
5. Submit a [Pull Request][github-prs]
[github-profile]: https://github.com/cgoldberg
[github-repo]: https://github.com/cgoldberg/xvfbwrapper
[github-issues]: https://github.com/cgoldberg/xvfbwrapper/issues
[github-prs]: https://github.com/cgoldberg/xvfbwrapper/pulls
[pypi-home]: https://pypi.org/project/xvfbwrapper
[mit-license]: https://raw.githubusercontent.com/cgoldberg/xvfbwrapper/refs/heads/master/LICENSE
Raw data
{
"_id": null,
"home_page": null,
"name": "xvfbwrapper",
"maintainer": "Corey Goldberg",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "Xvfb, headless, display, X11, X Window System",
"author": "Corey Goldberg",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f7/4f/830b1e7324facdb8d3e05008174c6b487f79b22b6869a4c58e351a4c55e0/xvfbwrapper-0.2.15.tar.gz",
"platform": null,
"description": "# xvfbwrapper\r\n\r\n#### Manage headless displays with Xvfb (X virtual framebuffer)\r\n\r\n- Copyright (c) 2012-2025 [Corey Goldberg][github-profile]\r\n- Development: [GitHub][github-repo]\r\n- Releases: [PyPI][pypi-home]\r\n- License: [MIT][mit-license]\r\n\r\n----\r\n\r\n## About\r\n\r\n`xvfbwrapper` is a Python module for controlling X11 virtual displays with Xvfb.\r\n\r\n----\r\n\r\n## What is Xvfb?\r\n\r\n\r\n`Xvfb` (X virtual framebuffer) is a display server implementing the X11\r\ndisplay server protocol. It runs in memory and does not require a physical\r\ndisplay or input device. Only a network layer is necessary.\r\n\r\n`Xvfb` allows GUI applications that use X Windows to run on a headless system.\r\n\r\n----\r\n\r\n## Installation\r\n\r\nOfficial releases are published on [PyPI][pypi-home]:\r\n\r\n```\r\npip install xvfbwrapper\r\n```\r\n\r\n----\r\n\r\n## System Requirements\r\n\r\n- Python 3.10+\r\n- X Window System (or Xwayland)\r\n- Xvfb (`sudo apt-get install xvfb`, `yum install xorg-x11-server-Xvfb`, etc)\r\n- Support for locking with `fcntl` system call (non-Windows systems)\r\n\r\n----\r\n\r\n## Examples\r\n\r\n#### Basic Usage:\r\n\r\nNote: Always either wrap your usage of `Xvfb()` with try/finally, or use it as\r\na context manager to ensure the display is stopped. If you don't, you'll end up\r\nwith a bunch of junk in `/tmp` if errors occur.\r\n\r\n```python\r\nfrom xvfbwrapper import Xvfb\r\n\r\nxvfb = Xvfb()\r\nxvfb.start()\r\ntry:\r\n # launch stuff inside virtual display here\r\nfinally:\r\n xvfb.stop()\r\n```\r\n\r\n#### Usage as a context manager:\r\n\r\n```python\r\nfrom xvfbwrapper import Xvfb\r\n\r\nwith Xvfb():\r\n # launch stuff inside virtual display here\r\n # (Xvfb will stop when this block completes)\r\n```\r\n\r\n#### Specifying display geometry:\r\n\r\n```python\r\nfrom xvfbwrapper import Xvfb\r\n\r\nxvfb = Xvfb(width=1280, height=720)\r\nxvfb.start()\r\ntry:\r\n # launch stuff inside virtual display here\r\nfinally:\r\n xvfb.stop()\r\n```\r\n\r\n#### Specifying display number:\r\n\r\n```python\r\nfrom xvfbwrapper import Xvfb\r\n\r\nxvfb = Xvfb(display=23)\r\nxvfb.start()\r\n# Xvfb is started with display :23\r\n# see vdisplay.new_display\r\ntry:\r\n # launch stuff inside virtual display here\r\nfinally:\r\n xvfb.stop()\r\n```\r\n\r\n#### Multithreaded execution:\r\n\r\nTo run several Xvfb displays at the same time, you can use the `environ`\r\nkeyword when starting the `Xvfb` instances. This provides isolation between\r\nprocesses or threads. Be sure to use the environment dictionary you initialize\r\n`Xvfb` with in your subsequent calls. Also, if you wish to inherit your current\r\nenvironment, you must use the copy method of `os.environ` and not simply\r\nassign a new variable to `os.environ`:\r\n\r\n```python\r\nimport os\r\n\r\nfrom xvfbwrapper import Xvfb\r\n\r\nisolated_environment1 = os.environ.copy()\r\nxvfb1 = Xvfb(environ=isolated_environment1)\r\nxvfb1.start()\r\n\r\nisolated_environment2 = os.environ.copy()\r\nxvfb2 = Xvfb(environ=isolated_environment2)\r\nxvfb2.start()\r\n\r\ntry:\r\n # launch stuff inside virtual displays here\r\nfinally:\r\n xvfb1.stop()\r\n xvfb2.stop()\r\n```\r\n\r\n#### Usage in testing - headless Selenium WebDriver tests:\r\n\r\nThis is a test using `selenium` and `xvfbwrapper` to run tests\r\non Chrome with a headless display. (see: [selenium docs][selenium-docs])\r\n\r\n[selenium-docs]: https://www.selenium.dev/selenium/docs/api/py\r\n\r\n```python\r\nimport os\r\nimport unittest\r\n\r\nfrom selenium import webdriver\r\nfrom xvfbwrapper import Xvfb\r\n\r\n# force X11 in case we are running on a Wayland system\r\nos.environ[\"XDG_SESSION_TYPE\"] = \"x11\"\r\n\r\n\r\nclass TestPage(unittest.TestCase):\r\n\r\n def setUp(self):\r\n xvfb = Xvfb()\r\n xvfb.start()\r\n self.driver = webdriver.Chrome()\r\n self.addCleanup(xvfb.stop)\r\n self.addCleanup(self.driver.quit)\r\n\r\n def test_selenium_homepage(self):\r\n self.driver.get(\"https://www.selenium.dev\")\r\n self.assertIn(\"Selenium\", self.driver.title)\r\n\r\n\r\nif __name__ == \"__main__\":\r\n unittest.main()\r\n```\r\n\r\n- virtual display is launched\r\n- browser launches inside virtual display (headless)\r\n- browser quits during cleanup\r\n- virtual display stops during cleanup\r\n\r\n----\r\n\r\n## xvfbwrapper Issues\r\n\r\nTo report a bug or request a new feature, please open an issue on [GitHub][github-issues].\r\n\r\n----\r\n\r\n## xvfbwrapper Development\r\n\r\n1. Fork the project repo on [GitHub][github-repo]\r\n\r\n2. Clone the repo:\r\n\r\n ```\r\n git clone https://github.com/<USERNAME>/xvfbwrapper.git\r\n cd xvfbwrapper\r\n ```\r\n\r\n3. Make changes and run the tests:\r\n\r\n Create a virtual env and install required testing packages:\r\n\r\n ```\r\n python -m venv venv\r\n source ./venv/bin/activate\r\n pip install --editable --group dev --group test .\r\n ```\r\n\r\n Run all tests in the default Python environment::\r\n\r\n ```\r\n pytest\r\n ```\r\n\r\n Run all tests, linting, and type checking across all supported/installed\r\n Python environments:\r\n\r\n ```\r\n tox\r\n ```\r\n\r\n4. Commit and push your changes\r\n\r\n5. Submit a [Pull Request][github-prs]\r\n\r\n\r\n[github-profile]: https://github.com/cgoldberg\r\n[github-repo]: https://github.com/cgoldberg/xvfbwrapper\r\n[github-issues]: https://github.com/cgoldberg/xvfbwrapper/issues\r\n[github-prs]: https://github.com/cgoldberg/xvfbwrapper/pulls\r\n[pypi-home]: https://pypi.org/project/xvfbwrapper\r\n[mit-license]: https://raw.githubusercontent.com/cgoldberg/xvfbwrapper/refs/heads/master/LICENSE\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Manage headless displays with Xvfb (X virtual framebuffer)",
"version": "0.2.15",
"project_urls": {
"download": "https://pypi.org/project/xvfbwrapper",
"homepage": "https://github.com/cgoldberg/xvfbwrapper",
"source": "https://github.com/cgoldberg/xvfbwrapper"
},
"split_keywords": [
"xvfb",
" headless",
" display",
" x11",
" x window system"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0cd591d52203cff4ae6981a9ad9af80501de3e402b4122446f462f901d160572",
"md5": "a401881f84a21cc67f72f29eca606bea",
"sha256": "47a746bc2b95ea864e9a24b71dd67e6b71a4a51fecb63c55f2c5b552e2ee56ad"
},
"downloads": -1,
"filename": "xvfbwrapper-0.2.15-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a401881f84a21cc67f72f29eca606bea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 6224,
"upload_time": "2025-10-20T12:53:08",
"upload_time_iso_8601": "2025-10-20T12:53:08.389230Z",
"url": "https://files.pythonhosted.org/packages/0c/d5/91d52203cff4ae6981a9ad9af80501de3e402b4122446f462f901d160572/xvfbwrapper-0.2.15-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f74f830b1e7324facdb8d3e05008174c6b487f79b22b6869a4c58e351a4c55e0",
"md5": "7f24107c68dd80266c3f30c8d773c22f",
"sha256": "695a4580ab4c9f69b653629ec243a873107536845879356f98d27569c43dac7e"
},
"downloads": -1,
"filename": "xvfbwrapper-0.2.15.tar.gz",
"has_sig": false,
"md5_digest": "7f24107c68dd80266c3f30c8d773c22f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 9027,
"upload_time": "2025-10-20T12:53:09",
"upload_time_iso_8601": "2025-10-20T12:53:09.461024Z",
"url": "https://files.pythonhosted.org/packages/f7/4f/830b1e7324facdb8d3e05008174c6b487f79b22b6869a4c58e351a4c55e0/xvfbwrapper-0.2.15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 12:53:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cgoldberg",
"github_project": "xvfbwrapper",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "xvfbwrapper"
}
JSON
