cv2.imread and VideoCapture fail silently — what are the limits of making OpenCV loading reproducible across machines?

Answer

OpenCV does not provide a strict mode that turns the silent‑failure returns of cv2.imread and cv2.VideoCapture into exceptions. The only guaranteed way to detect a problem is to check the return value (None for imread or isOpened() for VideoCapture) after each call.

Confirmed facts from the research

• cv2.imread returns None for any failure (missing file, unreadable format, missing codec) and never raises.
• cv2.VideoCapture reports success only via isOpened(); specifying a backend flag such as cv2.CAP_FFMPEG influences which backend is tried first but does not guarantee that the selected backend can decode the requested codec.
• Pinning an exact wheel version (e.g., opencv-python==4.9.0.80) locks the compiled‑in codecs and backends, yet runtime availability of external libraries (system FFmpeg, GStreamer, V4L2) can still cause silent failures if those libraries are missing or lack required decoders.
• Environment variables OPENCV_VIDEOIO_PRIORITY_* affect backend selection order, but they are ignored when the requested backend is not present in the OpenCV build or fails to initialize, causing OpenCV to silently fall back to the next usable backend.

Steps to achieve reproducible loading

1. Pin the exact OpenCV wheel in your requirements (opencv-python==<version> or the contrib variant).
2. When creating a VideoCapture, pass an explicit API preference (e.g., cv2.VideoCapture(path, cv2.CAP_FFMPEG)) to bias the backend.
3. After every imread call, test if img is None: and handle the error (log, raise, skip). After every VideoCapture construction, test if not cap.isOpened():.
4. Optionally, verify the build with print(cv2.getBuildInformation()) on each machine to confirm identical compiled backends and codec lists.
5. If silent failures persist, install the missing system codec libraries (e.g., FFmpeg packages) or use a headless/OpenCV build that bundles FFmpeg so the decoder is self‑contained.

If you still observe silent failures after these steps, please share the output of cv2.getBuildInformation() and the list of installed system codec libraries (e.g., ffmpeg -codecs) so we can pinpoint whether the missing decoder is at the wheel or system level.