Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

cv2.imshow raises 'not implemented' because the wrong OpenCV package is installed

Errorcv2.error raised by cv2.imshow() saying the function is not implemented

Short answer

The headless OpenCV packages are built without any GUI code, so cv2.imshow cannot open a window. It also fails when several opencv packages are installed together, because they share the cv2 name. List what pip has installed, remove every opencv package, then install only opencv-python.

  • Applies to opencv-python 4.x, pip 25, Python 3.12, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List every OpenCV package pip knows about in the environment that runs your script.

    python -m pip list | grep -i opencv
  2. 2Match what you see, then jump to its fix

    1. 1pip list shows opencv-python-headless or opencv-contrib-python-headlessA headless package is installedFix
    2. 2pip list shows two or more opencv entriesMore than one OpenCV package was installed over each otherFix

What does the error look like?

  • cv2.error raised by cv2.imshow() saying the function is not implemented
  • cv2.imshow() works in one environment and fails in another

Cause 1 of 2

A headless package is installed

1Check

The project states that its headless wheels have all GUI dependencies disabled at build time and are meant for code that never calls cv2.imshow.

python -m pip list | grep -i headless

2Fix

Replace the headless package with the desktop one. Remove all OpenCV packages first, then install one.

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

3Verify

Open a window from a tiny script on a machine that has a display.

python -c "import cv2, numpy as np; cv2.imshow('t', np.zeros((100,100,3), np.uint8)); cv2.waitKey(1000)"

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 2

More than one OpenCV package was installed over each other

1Check

All four packages put their code in the same cv2 module, so whichever was installed last can overwrite files from the other. The README says to select only one.

python -m pip list | grep -i opencv

2Fix

Uninstall every OpenCV package and reinstall just one. A dependency can pull in a headless build, so check pip list again after installing your other requirements.

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

3Verify

Only one OpenCV line remains.

python -m pip list | grep -i opencv

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Use opencv-python on a desktop and opencv-python-headless on servers and in containers, never both.
  • Keep one virtual environment per project so a global install cannot mix packages.
  • On a server with no display, save frames with cv2.imwrite instead of showing them.

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?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.