OpenCV cap read returns false on Raspberry Pi: warm up the capture

A still-image tool on a Raspberry Pi opens the camera with OpenCV, checks isOpened(), gets True — and read() still returns False. The libcamera preview tools show a picture, so the sensor, cable and driver all work, and the failure looks impossible. It is not: an open capture says nothing about whether a settled frame has made it through the image pipeline yet. This guide gives you one counting loop — 60 discarded reads — that separates the two real causes in about two seconds: first frames that are not ready yet, fixed with a warm-up burst, and an OpenCV build that cannot reach the CSI camera at all, fixed by moving the capture into Picamera2 or a GStreamer pipeline. Both fixes are committed below, with the arithmetic to size them.

What the symptom really says

read() returns a pair: ret, a bool, and frame, a NumPy array or None. ret == False means "no decodable frame on this call" — it does not mean the camera is unplugged. isOpened() == True means a driver accepted a device node; it says nothing about frames flowing.

On Raspberry Pi OS Bookworm the CSI camera module sits behind libcamera. Its /dev/video* nodes belong to an image-processing pipeline that libcamera itself drives, so a V4L2-style open can succeed on a node that never hands OpenCV a usable frame. That is exactly the True/False pair in the failing script.

The zeros from vcgencmd get_camera — supported=0 detected=0, libcamera interfaces=0 — are normal on Bookworm when the camera runs on libcamera. That firmware-level check predates the libcamera path and reports zeros anyway; it does not mean the camera is missing. A working libcamera-hello preview already proves the sensor, cable and driver, so leave the ribbon cable connected.

This fault family has a louder cousin: a cap.read() call that never returns at all. On a depth camera that one lives in the capture middleware, not the camera — see OpenCV stuck at cap.read on a depth camera.

One loop names the fault

Run this once before changing anything:

import cv2

cap = cv2.VideoCapture(0)    # int: index of the first capture device
ok = 0                       # int: calls that returned a usable frame
for _ in range(60):          # warm-up burst, counted in frames
    ret, frame = cap.read()  # ret: bool; frame: numpy.ndarray or None
    if ret and frame is not None:
        ok += 1
print("good frames:", ok, "of 60 | backend:", cap.getBackendName())
cap.release()

The count decides:

• 1 or more good frames — the stream works and start-up was the whole problem. Take the warm-up fix below.
• 0 good frames, with libcamera-hello still previewing — OpenCV cannot reach the CSI camera's image path. Take the capture-path fix below.

getBackendName() prints which backend answered; on a failing CSI camera it typically reports V4L2, which matches the diagnosis.

Cause 1: the first frames are not ready yet

Opening the device starts the stream, but the pipeline needs start-up time before an image worth saving exists. Early buffers can come back empty or incomplete; the image processor still has to debayer the raw sensor data, apply white balance, and let auto exposure converge over several frames. What you see varies by backend and version: read() reports False until the first complete frame lands, or it reports True with a pure black frame — the quiet version of the same fault.

None of that is a defect, and none of it is Pi-specific: every embedded capture pays this start-up cost, and the walkthrough on getting the first image on an embedded vision prototype treats it as step one. The tested value that clears it here is a 60-frame discard. The same discard-and-grab-fresh rule applies mid-stream — incomplete frames stay incomplete, so you drop them and take a fresh one rather than waiting for them to finish.

Fix: discard a warm-up burst, then take the still

1. Open the capture once and confirm isOpened().
2. Read for up to 60 frames, counting good frames, and stop early once 10 land in a row.
3. Take one more read as the still.
4. Save it with cv2.imwrite(); keep the capture open if more stills follow.

import cv2
from datetime import datetime

DISCARD_MAX = 60   # int: burst ceiling, in frames
GOOD_MIN = 10      # int: settled frames required before the still

cap = cv2.VideoCapture(0)
assert cap.isOpened(), "device did not open"

good = 0
for _ in range(DISCARD_MAX):
    ret, frame = cap.read()
    if ret and frame is not None:
        good += 1
        if good >= GOOD_MIN:
            break

ret, frame = cap.read()          # the still itself
assert ret and frame is not None, "no settled frame inside the burst"
path = datetime.now().strftime("%Y%m%d_%H%M%S") + ".jpg"
assert cv2.imwrite(path, frame), "file write failed"
print("saved", path, frame.shape)  # proof a real image reached the disk

Size the burst in frames, not seconds, because the frame period moves with the light:

with fps in frames per second, N in frames, and both times in seconds. At 30 fps one frame takes 1/30 s ≈ 33.3 ms, so a 60-frame burst costs about 2.0 s. In a dim room the exposure stretches; with a 50 ms exposure the period cannot be shorter than 50 ms, and the same burst takes at least 3.0 s. Budget 2-4 s of start-up, and size it from the rate the camera actually delivers — reading the frame rate reliably in OpenCV beats assuming 30.

Cause 2: the OpenCV build cannot reach the CSI camera

If the loop reports 0 good frames on every run while libcamera-hello still previews, the count has named a different fault: this OpenCV has no route into the libcamera stack. The standard opencv-python wheels speak V4L2; on Bookworm they land on a device node whose pixel path only libcamera can drive, so every read() fails forever. The libcamera tools succeed because they talk to libcamera directly and run the image processor themselves. The same holds across the Pi 3, Pi 4 and Pi 5 on Bookworm.

Move the capture into a path OpenCV can digest:

1. Picamera2. It ships with Raspberry Pi OS, drives libcamera natively, and its still-capture call hands you a NumPy array that OpenCV's processing and file-writing functions accept directly. This is the smallest change to a Python tool.
2. A GStreamer pipeline. Open cv2.VideoCapture with the GStreamer backend and a pipeline string that pulls from the libcamera source element. This needs an OpenCV build compiled with GStreamer support.
3. A USB webcam. A standard UVC camera enumerates as an ordinary V4L2 device, opens at index 0, and the warm-up burst alone covers its start-up.

For the camera-to-code routes on this board in more depth, see machine vision camera on Raspberry Pi: build the capture stack.

One boundary before hardware shopping: machine-vision cameras — the area scan cameras and board-level cameras in the shop — speak GigE Vision or USB3 Vision. They never appear at device index 0; you open them through a GenICam-based SDK or the vendor's GStreamer source. The camera finder filters by interface if the project steps up from a webcam module.

Keep the capture healthy in production

• Open once, keep it. Every reopen re-pays the 2-3 s warm-up. Grab continuously in the background and hold the newest good frame, so a triggered still costs one read instead of a restart; draining the buffer queue keeps that newest-frame read free of duplicates.
• Reopen deliberately after a stall. After a sleep, a cable swap or a reconnect, release the capture, reopen it, re-warm it — and wake the capture before you stream again rather than trusting the first read.
• Log the count, not just the crash. "41 of 60 good" in a log is a diagnosis; "read failed" is not.
• Watchdog above the warm-up. Set any ready-timeout at the 2-4 s burst plus margin — 5 s is a workable figure.

When the still is triggered by a fault or a line event rather than a keystroke, the same open-warm-grab structure carries over — fault-triggered video capture with OpenCV on an automation line walks that pattern end to end.

Quick checklist

• isOpened() == True means the node opened — not that frames flow.
• Run the 60-read counter before touching code, drivers or cables.
• 1 or more good frames → warm-up case: hold 10 settled frames before the still.
• 0 good frames with a working libcamera-hello → capture-path case: Picamera2, GStreamer or a UVC webcam.
• vcgencmd get_camera zeros on Bookworm are normal; do not chase them.
• Keep one capture open between stills; reopen and re-warm after any reconnect.
• Budget any ready-timeout at the 2-4 s burst plus margin.

More fixes in this family sit on the systems topic page.