Learn AI Create the Future — with Pranay
Main site

Error database

cv2.error: The function is not implemented. Rebuild the library with Windows, GTK+ ... (imshow)

Your OpenCV build has no GUI support — usually the headless variant is installed, or a server has no display. Install opencv-python (not headless), or save images instead of showing them.

The message you saw
cv2.error: The function is not implemented. Rebuild the library with Windows, GTK+ ... (imshow)

By Updated

The error

Output
cv2.error: OpenCV(4.10.0) ... 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 'cvShowImage'

A related Linux import-time failure:

Output
ImportError: libGL.so.1: cannot open shared object file: No such file or directory

What it means

cv2.imshow (and waitKey, namedWindow) need GUI machinery compiled into OpenCV and present on the system. Your installed build has none — the message's advice to "rebuild the library" predates the pip packages and is misleading today. With pip installs, nobody rebuilds anything; you swap which prebuilt variant is installed.

Why it happens

Three situations:

  • opencv-python-headless is installed. The headless variant deliberately omits GUI support for servers. It arrives silently as a dependency of other packages, then shadows or replaces the GUI build.
  • Both variants are installed, and the headless one is winning.
  • There is no display at all — Docker, SSH sessions, CI, cloud notebooks. GUI OpenCV cannot conjure a screen that does not exist.

The libGL.so.1 variant is Docker/slim-Linux specific: even importing GUI OpenCV needs the OpenGL runtime library the image lacks.

How to fix it

1. On a desktop machine: make opencv-python the only variant.

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

Uninstall all four first — order and duplication are exactly what causes the shadowing. Restart the kernel afterwards.

2. On servers, Docker and notebooks: do not imshow — save or plot.

python
cv2.imwrite("debug_frame.png", img)

Or display inline in a notebook via matplotlib (converting BGR to RGB, since OpenCV and matplotlib disagree on channel order):

python
import matplotlib.pyplot as plt
plt.imshow(cv2.cvtColor(img, cv2.COLOR_BGR2RGB))
plt.axis("off")

This is the intended workflow with headless OpenCV, not a workaround.

3. For libGL.so.1 in Docker, either install the library or go headless.

dockerfile
RUN apt-get update && apt-get install -y libgl1 libglib2.0-0

Or cleaner — depend on opencv-python-headless in the image and skip the system libraries entirely. Headless imports without libGL.

4. If a package keeps dragging headless back in, pin the GUI build after it in requirements, or isolate the conflicting tool in its own environment. Reinstalling opencv-python after the offender is the practical unblock.

How to prevent it

Choose the variant per target: GUI build on workstations, headless in requirements for servers and images. Keep the choice explicit in each environment's requirements file so dependency chains cannot decide it for you.