cv2.imshow error: The function is not implemented (tested)

cv2.error: (-2:Unspecified error) The function is not implemented. Rebuild the library with Windows, GTK+ 2.x or Cocoa support from cv2.imshow() means the cv2 you import has no GUI backend: usually opencv-python-headless, often installed on top of opencv-python. Keep only one package and reinstall it, or save images with cv2.imwrite on headless machines.

1. Reproduce it: opencv-python-headless has no GUI

b1.py:

import cv2, numpy as np
print("cv2", cv2.__version__)
img = np.zeros((40, 60, 3), np.uint8)
for name, fn in [("imshow", lambda: cv2.imshow("win", img)),
                 ("waitKey", lambda: cv2.waitKey(1)),
                 ("namedWindow", lambda: cv2.namedWindow("win")),
                 ("destroyAllWindows", lambda: cv2.destroyAllWindows())]:
    try:
        r = fn()
        print(f"{name}: OK -> {r}")
    except cv2.error as ex:
        print(f"{name}:")
        for l in str(ex).splitlines():
            if l.strip():
                print("  " + l.strip())

Output (opencv-python-headless 5.0.0, Python 3.13.5, Linux):

cv2 5.0.0
imshow:
  OpenCV(5.0.0) /io/opencv/modules/highgui/src/window.cpp:1215: error: (-2:Unspecified error) The function is not implemented. Rebuild the library with Windows, GTK+ 2.x or Cocoa support. If you are on Ubuntu or Debian, install libgtk2.0-dev and pkg-config, then re-run cmake or configure script in function 'showImageImpl'
waitKey:
  OpenCV(5.0.0) /io/opencv/modules/highgui/src/window.cpp:1262: error: (-2:Unspecified error) The function is not implemented. Rebuild the library with Windows, GTK+ 2.x or Cocoa support. If you are on Ubuntu or Debian, install libgtk2.0-dev and pkg-config, then re-run cmake or configure script in function 'waitKeyImpl'
namedWindow:
  OpenCV(5.0.0) /io/opencv/modules/highgui/src/window.cpp:1200: error: (-2:Unspecified error) The function is not implemented. Rebuild the library with Windows, GTK+ 2.x or Cocoa support. If you are on Ubuntu or Debian, install libgtk2.0-dev and pkg-config, then re-run cmake or configure script in function 'namedWindowImpl'
destroyAllWindows:
  OpenCV(5.0.0) /io/opencv/modules/highgui/src/window.cpp:1210: error: (-2:Unspecified error) The function is not implemented. Rebuild the library with Windows, GTK+ 2.x or Cocoa support. If you are on Ubuntu or Debian, install libgtk2.0-dev and pkg-config, then re-run cmake or configure script in function 'destroyAllWindowsImpl'

• Every window function (imshow, waitKey, namedWindow, destroyAllWindows) raises the same (-2:Unspecified error) The function is not implemented. Image processing (imread, cvtColor, resize, imwrite) still works.
• The message tells you to install libgtk2.0-dev and re-run cmake. That only applies if you compile OpenCV yourself. With pip wheels, it means the installed cv2 was built without a GUI backend.

2. Check which build you actually import

b2.py:

import cv2, numpy as np, os
from importlib.metadata import version, PackageNotFoundError
for d in ("opencv-python", "opencv-python-headless"):
    try: print(d, version(d))
    except PackageNotFoundError: print(d, "not installed")
gui = [l.strip() for l in cv2.getBuildInformation().splitlines() if l.strip().startswith("GUI:")]
print(gui[0])
print("DISPLAY =", os.environ.get("DISPLAY"))

Installing both packages into one venv with pip:

$ pip install -q opencv-python
$ python b2.py
opencv-python 5.0.0.93
opencv-python-headless not installed
GUI:                           QT5
DISPLAY = None
$ pip install -q opencv-python-headless
$ python b2.py
opencv-python 5.0.0.93
opencv-python-headless 5.0.0.93
GUI:                           NONE
DISPLAY = None
$ pip uninstall -y -q opencv-python-headless
$ python -c "import cv2; print(cv2.__version__)"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
    import cv2; print(cv2.__version__)
                      ^^^^^^^^^^^^^^^
AttributeError: module 'cv2' has no attribute '__version__'
$ pip install -q --force-reinstall opencv-python
$ python b2.py
opencv-python 5.0.0.93
opencv-python-headless not installed
GUI:                           QT5
DISPLAY = None

• opencv-python and opencv-python-headless both install into the same cv2/ folder. Whichever was installed last wins: installing headless on top switched GUI: from QT5 to NONE, and imshow then fails as in section 1. This often happens silently when another package (e.g. a library that depends on opencv-python-headless) pulls the headless build in.
• Uninstalling one of the two deletes shared files: afterwards import cv2 still "works" but the module is broken (module 'cv2' has no attribute '__version__').
• The fix is to keep exactly one OpenCV package and reinstall it: pip uninstall -y opencv-python opencv-python-headless, then pip install opencv-python (or pip install --force-reinstall opencv-python as above). If you use contrib modules, the same rule applies to opencv-contrib-python vs opencv-contrib-python-headless.

3. GUI build but no display: the Qt "xcb" abort

b3.py:

import cv2, numpy as np
img = np.zeros((40, 60, 3), np.uint8)
cv2.imshow("win", img)
cv2.waitKey(1)
print("shown")

With opencv-python (GUI: QT5) on a server, in Docker or over SSH without X forwarding:

$ echo $DISPLAY

$ python b3.py
qt.qpa.xcb: could not connect to display 
qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in ".venv/lib/python3.13/site-packages/cv2/qt/plugins" 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: xcb.

Aborted
exit code: 134

• This is not a Python exception: Qt aborts the whole process (exit code 134), so try/except cannot catch it.
• QT_QPA_PLATFORM=offscreen does not help with the pip wheel; it only ships the xcb plugin:

$ QT_QPA_PLATFORM=offscreen python b3.py
qt.qpa.plugin: Could not find the Qt platform plugin "offscreen" in ".venv/lib/python3.13/site-packages/cv2/qt/plugins"
This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.

Available platform plugins are: xcb.

exit code: 134

On a machine with no screen, there is nothing to show a window on. Use the headless build and write images to files instead (next section), or connect with ssh -X / set DISPLAY to a real X server.

4. Headless-safe display: imwrite or matplotlib

b5.py:

import cv2, numpy as np

def has_gui():
    for line in cv2.getBuildInformation().splitlines():
        if line.strip().startswith("GUI:"):
            return line.split(":", 1)[1].strip() != "NONE"
    return False

def show(name, img):
    if has_gui():
        cv2.imshow(name, img)
        cv2.waitKey(0)
        cv2.destroyAllWindows()
    else:
        ok = cv2.imwrite(f"{name}.png", img)
        print(f"no GUI backend: wrote {name}.png ({ok})")

img = np.zeros((40, 60, 3), np.uint8)
img[:, :20] = (255, 0, 0)          # BGR: blue stripe
print("GUI backend available:", has_gui())
show("preview", img)

# Jupyter / matplotlib: convert BGR -> RGB first or blue shows as red
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
print("pixel BGR", img[0, 0].tolist(), "-> RGB", rgb[0, 0].tolist())
plt.imshow(rgb); plt.axis("off"); plt.savefig("preview_mpl.png")
print("saved preview_mpl.png")

Output (opencv-python-headless 5.0.0, matplotlib 3.11.2):

GUI backend available: False
no GUI backend: wrote preview.png (True)
pixel BGR [255, 0, 0] -> RGB [0, 0, 255]
saved preview_mpl.png

• Read GUI: from cv2.getBuildInformation() to decide at runtime; fall back to cv2.imwrite(), which works in every build.
• In Jupyter, use matplotlib.pyplot.imshow instead of cv2.imshow, and convert with cv2.COLOR_BGR2RGB first: OpenCV stores pixels as BGR, so a blue [255, 0, 0] pixel would otherwise display as red.

Related: cv2.error (-215:Assertion failed) !_src.empty().

Written with AI assistance. Measured on 2026-10-23 with opencv-python 5.0.0.93, opencv-python-headless 5.0.0.93 and Python 3.13.5 on Linux (no display). Scripts ran verbatim and the output was pasted unedited. PlainTables is our extension; OpenCV is free.