Skip to main content Logo

Quis custodiet ipsos custodes?
Home | About | All pages | Cluster Status | RSS Feed

Expose any Qt5 program via VNC

Published: 20-09-2021 | Author: Remy van Elst | Text only version of this article

❗ This post is over two years old. It may no longer be up to date. Opinions may have changed.

Coffee Machine VNC

Remote Coffee Machine Qt GUI via VNC

A few months ago I wrote about Microsoft Teams running on a coffee machine. That was a fun work experiment where I got a VNC client running on the linux-based coffee machines that we produce at work. In the comments on hackernews Jean-Michaël Celerier pointed me to the reverse, a way to expose any Qt application over VNC. This article shows you how I use this feature to work on our Qt 5 based coffee machine frontend as well as how you can use this on your machine, for example, to expose Dolphin, the KDE file manager, over VNC.

Recently I removed all Google Ads from this site due to their invasive tracking, as well as Google Analytics. Please, if you found this content useful, consider a small donation using any of the options below:

I'm developing an open source monitoring app called Leaf Node Monitoring, for windows, linux & android. Go check it out!

Consider sponsoring me on Github. It means the world to me if you show your appreciation and you'll help pay the server costs.

You can also sponsor me by getting a Digital Ocean VPS. With this referral link you'll get $100 credit for 60 days.

Our Qt frontend for the coffee machines can run as a local application just fine, it's nothing more than a client towards an HTTP API. One other such client is our touchless feature, that exposes a part of the machine over MQtT to a website.

One issue with running the Qt application on my workstation is that remote media is not loaded. The coffee machine can display images and video (and show a QR code), but those images are dynamically loaded in QML, via a filesystem path that my machine does not have. I could setup an sshfs mount, but that would require fiddling with permissions. In the instances that I have to work on that part of the code I run the UI via VNC directly on a coffee machine, all the filesystem paths are available then.

Qt 5 applications via VNC

You can append a command line flag to any Qt application or set an environment variable to expose the application over VNC. The command line flag is -platform vnc and the environment variable is Qt_QPA_PLATFORM="vnc". Here is how to run Dolphin via VNC on port 5900:

Qt_QPA_PLATFORM="vnc"  dolphin
# or
dolphin -platform vnc

In the output you should see the following like:

QVncServer created on port 5900

The environment variable method is preferred as far as I can find online.

Use a VNC client to connect to, or if you have your firewall disabled, you can connect from any other host on the network. Here is how dolphin looks on my workstation, via VNC:

dolphin vnc

There is no window management and no title bar as you can see. There is also no way to password protect the VNC service. The colours might be a bit off since the colour depth via VNC can be different than your own screen.

The size of the VNC window can be controlled by appending :size=WxH, like so:


Here is KDiamond, a Bejeweled-type game running with a size parameter, you can see that the scaling is a bit off:

kdiamond -platform vnc:size=300x400



Qt Platform Abstraction and other technical details

The VNC plugin is a QPA (Qt Platform Abstraction) plugin. QPA plugins are responsible for the actual rendering of the Qt application, most often on screen. There are plugins for Android, Windows, Linux (xcb being the default for X11) and Wayland, but also for more exotic platforms like Haiku, WinRT or Mir.

Our coffee machine UI uses the EGLFS plugin for hardware accelerated graphical output without an X server. EGLFS is a platform plugin for running Qt5 applications on top of EGL and OpenGL ES 2.0, without an actual windowing system like X11 or Wayland. In addition to Qt Quick 2 and native OpenGL applications, EGLFS supports software-rendered windows, like QWidget, too.

There is even a WebGL plugin, to stream an application directly to a website. Couldn't get that to work, maybe an idea for a future article.

The VNC plugin is not documented well, but it was added in Qt 5.8. I found out that it also supports a port= parameter by peeking into the source code for QVncIntegration. I found the size=WxH parameter in the source as well.

Your platform must have the library installed for it to work, but often it's available with your distro's base Qt5 framework packages. My Arch Linux install got it with the default KDE5 installation and on Ubuntu the plugin file is provided by the package libqt5gui5, as the search on shows:

/usr/lib/i386-linux-gnu/qt5/plugins/platforms/    libqt5gui5 [i386] 

You can also query the available plugins on your system passing an invalid parameter to the -platform flag:

dolphin -platform garbage 


qt.qpa.plugin: Could not find the Qt platform plugin "garbage" in "" This
application failed to start because no Qt platform plugin could be
initialized. Reinstalling the application may fix this problem.

Available platform plugins are: eglfs, linuxfb, minimal, minimalegl,
offscreen, vnc, wayland-egl, wayland, wayland-xcomposite-egl,
wayland-xcomposite-glx, xcb.

Aborted (core dumped)

The core dump is rather sad, but you get the gist, This output is useful, instead of a generic error message like plugin not found, help the user by listing the available options. I often complain about Qt, but I have to give them this one, this error message is helpful.

For reference, on my Arch Linux system the following plugins are available:

$ ls /usr/lib/qt/plugins/platforms
total 1.5M
drwxr-xr-x  2 root root 4.0K Sep 16 19:55 .
drwxr-xr-x 62 root root  12K Sep 16 19:56 ..
-rwxr-xr-x  1 root root  18K Sep  4 23:24
-rwxr-xr-x  1 root root 466K Sep  4 23:24
-rwxr-xr-x  1 root root 138K Sep  4 23:24
-rwxr-xr-x  1 root root 171K Sep  4 23:24
-rwxr-xr-x  1 root root 182K Sep  4 23:24
-rwxr-xr-x  1 root root 238K Sep  4 23:24
-rwxr-xr-x  1 root root  66K Sep  7 09:14
-rwxr-xr-x  1 root root  18K Sep  7 09:14
-rwxr-xr-x  1 root root  75K Sep  7 09:14
-rwxr-xr-x  1 root root  54K Sep  7 09:14
-rwxr-xr-x  1 root root  18K Sep  4 23:24

If you know a way to get the WebGL plugin working, please let me know! I'd love to experiment with that, WebAssembly requires many changes to applications, but WebGL should be as simple as the VNC plugin, just a variable or command line argument.

Tags: articles , kde , linux , qml , qt , qt5 , ubuntu , vnc