OpenCV cv2.VideoCapture returning False on Linux server without GUI backend

cv2.VideoCapture returning False or failing to open video streams on a headless Linux server occurs because OpenCV defaults to video backends (such as GStreamer or X11/FFmpeg rendering pipes) that expect an active display server or GUI framework context ($DISPLAY). Additionally, standard opencv-python PyPI packages often bundle pre-compiled binaries missing headless FFmpeg backend bindings, or lack permissions to access hardware video decoders like /dev/video* and /dev/dri/.

Quick Fix

Force OpenCV to use the FFmpeg backend explicitly in Python, or install the dedicated headless OpenCV package via pip:

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

import cv2

cap = cv2.VideoCapture("video.mp4", cv2.CAP_FFMPEG)

Step-by-Step Resolution

1. Purge GUI-dependent OpenCV packages to prevent backend driver collisions on headless systems:

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

2. Install the headless distribution and FFmpeg system libraries:

sudo apt-get update && sudo apt-get install -y ffmpeg libsm6 libxext6
pip install opencv-python-headless

3. **Explicitly pass cv2.CAP_FFMPEG or cv2.CAP_V4L2** into cv2.VideoCapture depending on whether you are reading a video file/stream or a local capture device:

import cv2

# For video files or RTSP/HTTP streams: force CAP_FFMPEG
video_path = "input_stream.mp4"
cap = cv2.VideoCapture(video_path, cv2.CAP_FFMPEG)

# For hardware devices/webcams in headless Linux: force CAP_V4L2
# cap = cv2.VideoCapture(0, cv2.CAP_V4L2)

if not cap.isOpened():
    raise RuntimeError(f"Failed to open video source: {video_path}")

while cap.isOpened():
    ret, frame = cap.read()
    if not ret:
        break
    # Process frame in memory (no cv2.imshow)

cap.release()

Why This Fails for Some Users

• Unset GStreamer Environment Variables: If OpenCV was compiled with GStreamer support, it attempts to initialize X11/Wayland sinks unless explicitly suppressed by setting export GST_REGISTRY_FORK=0 or passing non-GUI pipeline elements.
• Missing Container Video Device Nodes: Inside Docker containers, accessing hardware devices like /dev/video0 fails unless the container is run with device mapping (--device=/dev/video0) or elevated privileges (--privileged).
• RTSP Codec and Transport Mismatches: Headless RTSP streaming via FFmpeg can silently drop connections if UDP packets are blocked by server firewalls; setting os.environ["OPENCV_FFMPEG_CAPTURE_OPTIONS"] = "rtsp_transport;udp" (or tcp) is required to force transport protocols.
• Calling cv2.imshow() in Headless Scripts: Invoking GUI-dependent display functions downstream in the script causes OpenCV to throw an error: (-218:No OpenGL support) or crash the entire execution thread on servers without an X11 display.