What is headless mode?
opencv-python-headless — OpenCV without a GUI
The opencv-python-headless package is identical to opencv-python except it removes all GUI dependencies (Qt, GTK, display libraries). This makes it:
- Smaller in size (no Qt libraries bundled)
- Safe to run in environments without a display (servers, Docker, CI/CD pipelines, cloud functions)
- Free from errors like
cannot connect to X serveror Qt platform plugin failures
The trade-off: cv2.imshow(), cv2.waitKey() and other GUI functions will not work. Use cv2.imwrite() to save images instead.
Install
Install opencv-python-headless
# Remove any existing OpenCV packages first:
C:\> pip uninstall opencv-python opencv-contrib-python opencv-python-headless -y
# Install headless:
C:\> pip install opencv-python-headless
Successfully installed opencv-python-headless-4.12.0.86
# Or headless + contrib:
C:\> pip install opencv-contrib-python-headless
When to use each
Headless vs standard package
| Scenario | Use |
|---|---|
| Desktop app, showing windows to user | opencv-python |
| Windows Server, no monitor attached | opencv-python-headless |
| Docker container / CI pipeline | opencv-python-headless |
| Flask / FastAPI image processing API | opencv-python-headless |
| Jupyter Notebook (no imshow needed) | opencv-python-headless |
| Need face recognition, SIFT etc. | opencv-contrib-python-headless |
Display alternatives
Show images without imshow()
import cv2
import matplotlib.pyplot as plt
# Save to disk:
cv2.imwrite("output.jpg", img)
# Show with matplotlib (works in Jupyter and scripts):
plt.imshow(cv2.cvtColor(img, cv2.COLOR_BGR2RGB))
plt.axis('off'); plt.show()
# Encode to bytes (for web APIs):
_, buf = cv2.imencode('.jpg', img)
jpg_bytes = buf.tobytes()
FAQ
Headless questions
cv2.imshow() raises an error in headless mode
This is expected. Headless OpenCV has the GUI functions removed. Replace
cv2.imshow() with cv2.imwrite() to save images, or use matplotlib for display in scripts and notebooks.Is opencv-python-headless faster?
Minimally. The processing performance (image operations, convolutions, etc.) is identical. Headless is slightly smaller on disk and avoids loading Qt libraries at import time, which can reduce startup time slightly.
Docker: which base image works with opencv-python-headless?
Any Python base image works:
python:3.11-slim is popular. Just pip install opencv-python-headless. No extra system packages needed since all dependencies are bundled in the wheel.