opencv-python-headless & opencv-contrib-python

[adelinopds]

"opencv-contrib-python",
"opencv-python-headless",

[ndonkoHenri]

opencv-python-headless 5.0.0.93 is now supported on Android and iOS: https://pypi.flet.dev/opencv-python-headless

opencv-python-headless is OpenCV without the desktop GUI module — the same import cv2 and the same image/vision APIs, minus imshow/namedWindow (which can't work on a phone anyway). It's the variant that augmentation and OCR libraries depend on.

Install

numpy comes in automatically as an OpenCV dependency:

dependencies = [
    "flet",
    "opencv-python-headless",
]

[tool.flet.android]
extract_packages = ["cv2"]

Minimal app

Run a real cv2 pipeline and show the result. Since there's no GUI, display images through Flet's Image control (it accepts raw PNG bytes) rather than cv2.imshow:

import flet as ft
import cv2
import numpy as np


def main(page: ft.Page):
    img = np.zeros((200, 200, 3), dtype=np.uint8)
    cv2.circle(img, (100, 100), 70, (0, 140, 255), -1)
    edges = cv2.Canny(cv2.cvtColor(img, cv2.COLOR_BGR2GRAY), 50, 150)
    ok, png = cv2.imencode(".png", edges)  # encode to PNG in memory

    page.add(
        ft.Text(
            f"cv2 {cv2.__version__}: {int((edges > 0).sum())} edge pixels",
            weight=ft.FontWeight.BOLD,
        ),
        ft.Image(src=png.tobytes(), width=200, height=200),
    )


ft.run(main)

On device this shows the edge-detected circle plus the computed edge-pixel count.

Recommendations

• Don't install both opencv-python and opencv-python-headless — both provide the cv2 module and will collide. Pick one; on mobile, headless is the natural choice, and it's what OCR/augmentation deps pull in.
• No GUI calls — cv2.imshow, namedWindow, waitKey are no-ops/errors here. Render results via ft.Image(src=<png bytes>) as above or using ft.RawImage.
• Heavy processing off the UI thread — wrap long pipelines (large images, video frames, dnn inference) in page.run_thread(...) so the UI stays responsive.
• The cv2.dnn module is included, so you can run ONNX models directly through OpenCV if you'd rather not add a separate runtime.

[ndonkoHenri]

opencv-contrib-python 5.0.0.93 is now supported on Android and iOS: https://pypi.flet.dev/opencv-contrib-python

opencv-contrib-python is OpenCV with the opencv_contrib extra modules folded into the same import cv2 — aruco, face, tracking, ximgproc, wechat_qrcode, img_hash and more, on top of everything the base OpenCV gives you.

Install

numpy comes in automatically as an OpenCV dependency:

# pyproject.toml
dependencies = [
    "flet",
    "opencv-contrib-python",
]

[tool.flet.android]
extract_packages = ["cv2"]

Minimal app

Run a real cv2 pipeline and show the result. There's no GUI on a phone, so display images through Flet controls rather than cv2.imshow:

import flet as ft
import cv2
import numpy as np


def main(page: ft.Page):
    img = np.zeros((200, 200, 3), dtype=np.uint8)
    cv2.circle(img, (100, 100), 70, (0, 140, 255), -1)
    edges = cv2.Canny(cv2.cvtColor(img, cv2.COLOR_BGR2GRAY), 50, 150)
    ok, png = cv2.imencode(".png", edges)

    page.add(
        ft.Text(
            f"cv2 {cv2.__version__}: {int((edges > 0).sum())} edge pixels",
            weight=ft.FontWeight.BOLD,
        ),
        ft.Image(src=png.tobytes(), width=200, height=200),  # src takes bytes
    )


ft.run(main)

For live/streaming frames (video, real-time filters, per-frame detection), ft.RawImage is a better fit than ft.Image — it takes a NumPy array directly (no per-frame PNG encode) and streams frames over a data channel at interactive rates. One caveat: OpenCV is BGR, RawImage expects RGB, so convert first:

raw = ft.RawImage(width=320, height=240)
page.add(raw)
for frame in your_frames():                        # BGR uint8 arrays
    await raw.render(cv2.cvtColor(frame, cv2.COLOR_BGR2RGB))   # numpy straight in

Recommendations

• Don't install both opencv-python/opencv-contrib-python (or their headless variants) — all provide the cv2 module and will collide. Pick one; use contrib only if you actually need the extra modules.
• cv2.rgbd / cv2.linemod are Android-only in this build (the iOS gate above). Everything else — aruco, face, ximgproc, wechat_qrcode, img_hash, dnn_superres, … — is on both platforms.
• No GUI calls — cv2.imshow/waitKey don't apply; render via ft.Image(src=<png bytes>) or ft.RawImage as shown.
• Heavy processing off the UI thread — wrap long pipelines in page.run_thread(...).