#737·RapidOCR

Make the OpenCV build selectable instead of hard-requiring opencv-python

Author: Classic298Created Sep 6, 2026Updated Sep 15, 2026

rapidocr hard-requires opencv_python, the GUI build. Projects that already pin opencv-python-headless end up with both installed. Both write the same cv2 package, so which one you actually get depends on install order, and the GUI build adds around 115 MB on x86_64 (mostly bundled Qt) plus a libGL requirement that headless containers do not have.

#185 asked to switch the dependency to headless and was declined because most packages depend on the GUI build. This is a different ask.

rapidocr only uses core, imgproc and imgcodecs, which every OpenCV build provides, so this is packaging only, no code change. Two shapes would work:

  1. Drop OpenCV from the base requirements entirely and offer extras: rapidocr[opencv] pulls opencv-python, rapidocr[opencv-headless] pulls opencv-python-headless. Projects that already have a cv2 install plain rapidocr and nothing else changes for them. A missing cv2 at import time raises a clear error naming the extras. The base package no longer runs out of the box, which the README and the error message cover.

  2. Keep opencv-python-headless as the base dependency and offer rapidocr[gui] for opencv-python. Headless is a strict subset, so existing users lose nothing except the GUI windows they were not using in a server context. easyocr and albumentations both ship headless as the default for the same reason.

Either one lets a downstream project stop carrying two OpenCV builds. Option 1 is the one that fully avoids the concern raised in #185, since rapidocr then no longer picks a build for anyone.

Context: Open WebUI ships rapidocr in its Docker image and pins opencv-python-headless, so every image today carries both builds. We are slimming the image (open-webui/open-webui#29721) and this is one of the larger items. Overriding rapidocr's declared dependency from our Dockerfile was rejected on our side, the fix belongs here, so this issue is what we are asking for instead.