How to run a Qt application in headless mode (without showing my GUI)

I have a QT application based on a QApplication and supposing that my application has a complex GUI (QDialog, QMainWindow...).

My Application can run in two modes:

with GUI
in headless mode

I would like to know how I can launch the application in headless mode (that is to say without GUI visible)

From a very basic code, below, what argument shall I have to allow this?

int main(int argc, char*argv[])
{
  QApplication app(argc, argv);
  // which option should I add to argv to run in headless mode
  return app.exec();
}

Solution

There are several options here. Either you need a Qt Console Application or you need a headless GUI Application.

You will find truly running a GUI in headless mode rather tricky. This applies in case you need to run the very same app in a Linux system which does not have the installed GUI libraries, like a minimal setup. Without extensive xorg and/or EGL libraries you'll find it impossible.

But fear not, you can do it with minimal impact by using either the Qt VNC platform plugin or with with the help of Xvfb. So in short

Solution 1: Hide it with Qt's VNC plugin

$ QT_QPA_PLATFORM="vnc"  ./my-app

it's the same as

$ ./my-app -platform vnc

You'll find that you software has a GUI but it's running in headless mode, in order to view the GUI you just connect to it with any vncviewer.

Solution 2: Avoid dependencies with Qt's VNC plugin

The same as the other solution, and you can just hide your GUI by not showing it.

Solution 3: Nullify render with offscreen render

This is rather similar to VNC but you'll get a totally null output, no way for GUI interaction:

$ ./my-app -platform offscreen

Solution 4: Run Xvfb and launch it there

You can run a fake Xorg server and run things over there.

export DISPLAY=:1
Xvfb :1 -screen 0 1024x768x16 &
./myapp &

From the given solutions I'd prefer the offscreen render, but your Qt compilation might not have the plugin or it might ask for xcb or egl libraries. It's your choice.