qt.qpa.plugin: Could not load the Qt platform plugin "xcb"

The error#

qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
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, xcb.

The process then aborts — often when calling cv2.imshow or plt.show.

What it means#

Qt is the GUI toolkit under matplotlib's QtAgg backend and OpenCV's Linux windows, and xcb is its plugin for talking to the X display system. The plugin file exists ("even though it was found") but failed to load — one of the system libraries it links against is absent, or two different Qt installations in one process are fighting. The message's advice to reinstall the application is rarely the fix.

Why it happens#

Slim Linux installs and Docker images lack pieces of the xcb library family; Qt6 notably needs libxcb-cursor0, which even desktop Ubuntu did not always ship. The other route is a Qt collision: opencv-python bundles its own Qt, and importing it alongside PyQt (matplotlib's QtAgg, Spyder, other GUI tools) puts two incompatible Qts in one process — whichever loads second breaks with exactly this message. Headless servers add a third route: X libraries present, but no display to connect to.

How to fix it#

1. Install the missing xcb libraries (Debian/Ubuntu).

sudo apt update
sudo apt install libxcb-cursor0 libxcb-xinerama0 libxcb-icccm4 libxcb-keysyms1 libxcb-shape0

libxcb-cursor0 alone fixes the majority of Qt6 cases. To see precisely which library is missing, run once with plugin debugging and read the report:

QT_DEBUG_PLUGINS=1 python your_script.py 2>&1 | grep -i "cannot load\|undefined"

2. If it appears when OpenCV and matplotlib/PyQt mix, de-duplicate Qt. Use headless OpenCV so only one Qt remains:

pip uninstall -y opencv-python
pip install opencv-python-headless

Display images through matplotlib instead of cv2.imshow. This is the standard resolution for the Spyder/PyQt-plus-OpenCV collision.

3. On a genuinely headless machine, stop asking for windows. Point Qt at its off-screen plugin for code you cannot change, or better, use file output:

export QT_QPA_PLATFORM=offscreen

And for matplotlib, the Agg-and-savefig pattern from the related page below.

4. Over SSH, enable X forwarding if you truly want remote windows. ssh -X user@host plus an X server on your side. For plots, saved files remain the less fragile habit.

How to prevent it#

In Docker images that need OpenCV, choose headless plus the libgl1/libglib2.0-0 pair, and never install GUI Qt at all. On desktops, keep one Qt per environment: either OpenCV's or PyQt's, not both. When building environments for GUI work, install the xcb set up front on slim distros.

Related errors#

• The function is not implemented (OpenCV GUI) — OpenCV GUI missing rather than broken
• Matplotlib is currently using agg — the graceful version of "no display"
• No module named 'cv2' — the OpenCV variant table