Jul 20, 2023

Python wrapper for Xvfb, Xephyr and Xvnc

PyVirtualDisplay is a python wrapper for Xvfb, Xephyr and Xvnc.

Pyvirtualdisplay is an incredibly powerful tool for those using FreeBSD and is classified under the x11 category of FreeBSD ports. Derived from the Python programming language, Pyvirtualdisplay makes it possible to operate any graphical software on a server without needing a dedicated display or physical access to the server’s graphics card.

Before we delve deeper, let’s understand what a FreeBSD port is. A FreeBSD port is a collection of files designed to automate the process of compiling an application from its source code. This helps in easier installation and management of software on FreeBSD. Pyvirtualdisplay is one such port under the category of x11. An x11 port involves graphical user interface libraries, which makes the task of handling graphical displays infinitely easier.

To start with Pyvirtualdisplay, make sure to have Python installed on your FreeBSD system. This is a prerequisite because it’s Python-based. If Python is not installed, you can use the FreeBSD port for Python, available at [Python Port for FreeBSD][1].

[1] https//

Upon confirming that Python is installed, you can proceed to install the Pyvirtualdisplay port using below commands

cd /usr/ports/x11/py-pyvirtualdisplay/
make install clean

After the installation process finishes, you’re ready to start using Pyvirtualdisplay.

Using Pyvirtualdisplay

In order to run, Pyvirtualdisplay needs a back-end and it supports two main back-ends Xvfb and Xephyr.

Xvfb or ‘X Virtual Framebuffer’ is an X server variant that operates entirely in memory, perfect for off-screen or ‘headless’ usage. To install Xvfb, run

cd /usr/ports/x11-servers/xorg-vfbserver/
make install clean

Alternatively, Xephyr is a kdrive based X Server targeting a window on a host X Server as its framebuffer. To install Xephyr, run

cd /usr/ports/x11-servers/xephyr/
make install clean

Once the back-end is installed, you can use Pyvirtualdisplay to create a virtual display

from pyvirtualdisplay.smartdisplay import SmartDisplay

with SmartDisplay as disp
    # your code here

With a few lines of code, Pyvirtualdisplay starts a virtual display that will be closed at the end of the with block.

Additional Features of Pyvirtualdisplay

One important feature of Pyvirtualdisplay is its support for screenshot functionality. You can capture a screenshot using the get_pixels method of the SmartDisplay class

from pyvirtualdisplay.smartdisplay import SmartDisplay

with SmartDisplay as disp
    # your code here
    screenshot = disp.get_pixels

The get_pixels method returns a string containing the pixel data in the format specified by the virtual display back-end.


Pyvirtualdisplay provides its users with significant benefits. Its ability to handle X11 makes it ideal for testing environments in software development, specifically for checking website appearance and response before public deployment. It can be particularly beneficial when used in conjunction with other testing tools, like [Selenium][2].

[2] https//

Also, it’s useful in isolation environments where multiple X sessions are needed. For instance, in scenarios where you need to execute two applications with different X settings simultaneously.

For BSD users interested in leveraging power of more FreeBSD ports, [Nmap][3], a security scanner, and [Wireshark][4], a network capturing and protocol analysis software, are advised for anyone concerned with IT security.

[3] https// [4] https//

In conclusion, the Pyvirtualdisplay port is a robust utility for FreeBSD users, aiding in comprehensive testing environments and seamless operation of X11 based applications within various, isolation-requisite scenarios.

Checkout these related ports:
  • Zenity - Display GNOME dialogs from the command line
  • Yelp - Help browser for the GNOME desktop
  • Yeahconsole - Terminal wrapper for creating drop-down consoles
  • Yalias - Enhanced execution box with regex pattern matching
  • Yakuake - Drop-down terminal emulator for KDE
  • Yad - Display GNOME dialogs from the command line
  • Xzoom - Magnify, rotate, mirror the image on the X11 screen
  • Xxkb - XKB keyboard layout indicator and switcher
  • Xwud - Image displayer for X
  • Xwit - X interface tool
  • Xwinwrap - XWinWrap replace a desktop background with a movie or screensaver
  • Xwininfo - Window information utility for X
  • Xwd - Dump an image of an X window
  • Xwatchwin - Watch a window on another X server
  • Xvt - Xterm replacement, supporting color, transparency, and more, with less