cv2.imshow raises 'not implemented' because the wrong OpenCV package is installed
cv2.error raised by cv2.imshow() saying the function is not implementedShort 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.
Fix it fast
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 opencv2Match what you see, then jump to its fix
What does the error look like?
cv2.error raised by cv2.imshow() saying the function is not implementedcv2.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 headless2Fix
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-python3Verify
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
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 opencv2Fix
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-python3Verify
Only one OpenCV line remains.
python -m pip list | grep -i opencvConfirmed by raw.githubusercontent.com
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:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Servers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
pip install Cython succeeded, but the shell cannot find cythonize
a pip warning that a script was installed to a directory outside PATH
pip put the cythonize script in a folder your shell does not search.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fixServers
You cannot pip install packages inside an Ubuntu Docker container
error: externally-managed-environment
If pip is missing, install the python3-pip package with apt, in the same RUN as apt-get update.
3 causes, each with a fixServers
A PyInstaller app says GLIBC not found on another Linux machine
version `GLIBC_2.35' not found (required by /tmp/_MEIqx6YRS/libpython3.10.so.1.0)
PyInstaller does not bundle libc.
2 causes, each with a fix