A Qt app on Linux will not start: xcb platform plugin found but not loaded
qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.Short answer
Qt found the xcb plugin file but the plugin could not load, almost always because a library it needs, such as libxcb-cursor0, is missing. Turn on QT_DEBUG_PLUGINS to see the missing library, install it, or start the app on another platform with QT_QPA_PLATFORM.
Fix it fast
1Find out which cause you have
Run the app with plugin diagnostics on. Qt then prints details for every plugin it tries to load, including why xcb failed.
QT_DEBUG_PLUGINS=1 ./my-qt-app2Match what you see, then jump to its fix
- 1
The QT_DEBUG_PLUGINS output names a shared library it cannot find, for example a libxcb library.A library the xcb plugin depends on is not installedFix - 2
The app runs under another desktop session type than the plugin expects, or QT_QPA_PLATFORM is set to something unintended.Qt picked a platform plugin that does not suit the sessionFix
- 1
What does the error look like?
qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
Cause 1 of 2
A library the xcb plugin depends on is not installed
1Check
Qt's Linux requirements table lists xcb-cursor0, packaged as libxcb-cursor0, among the platform dependencies for the xcb plugin. Check whether that package is installed.
dpkg -l libxcb-cursor02Fix
Install the package that provides the missing library. For xcb-cursor it is libxcb-cursor0 on Ubuntu.
sudo apt install libxcb-cursor03Verify
The app starts without the plugin message.
./my-qt-appConfirmed by doc.qt.io
Cause 2 of 2
Qt picked a platform plugin that does not suit the session
1Check
Qt chooses a default platform plugin for the system, and the QT_QPA_PLATFORM variable or the -platform argument overrides it. A leftover export in a shell profile is enough to force xcb.
echo "$QT_QPA_PLATFORM"
echo "$XDG_SESSION_TYPE"2Fix
Unset a wrong override, or give Qt an ordered list; it uses the first plugin that is available.
unset QT_QPA_PLATFORM
QT_QPA_PLATFORM="xcb;wayland" ./my-qt-app3Verify
The app opens a window.
QT_QPA_PLATFORM=wayland ./my-qt-appConfirmed by doc.qt.io
How do I stop it coming back?
- Install the platform libraries from Qt's Linux requirements page on every build and runtime machine, including containers.
- Keep QT_QPA_PLATFORM out of shell profiles; set it per run.
- Run the app once with QT_DEBUG_PLUGINS=1 on a clean machine before shipping a release.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Related fixes
Mobile apps
adb cannot start because something already holds its port
adb start-server failed
The adb server must bind local TCP port 5037, and every adb client talks to it there.
2 causes, each with a fixMobile apps
adb cannot connect to its daemon or start the server
* daemon started successfully *
The adb server is a background process on your computer that listens on TCP port 5037.
2 causes, each with a fixMobile apps
adb prints 'server version doesn't match this client; killing...'
adb server version doesn't match this client; killing...
adb runs a background server, and every adb command is a client.
3 causes, each with a fixMobile apps
adb tcpip 5555 fails because no device is found
adb: more than one device/emulator
adb tcpip only works while the device is attached and listed by adb, because it tells the phone to start listening on port 5555.
4 causes, each with a fixMobile apps
The Android Emulator says /dev/kvm is not found
KVM acceleration can NOT be used
The emulator wants a hypervisor and cannot find one.
4 causes, each with a fixMobile apps
The emulator says the GPU driver is unsupported and falls back to software
vulkan-1.dll cannot be found
The emulator picks a graphics mode when it starts.
4 causes, each with a fix