releasing 0.30.0

[Borda]

0.30.0: Run supervision without OpenCV

📋 Summary

supervision 0.30.0 makes OpenCV optional. A new private _cv2/ backend (NumPy and Pillow, with PyAV for the video path) reimplements every OpenCV call the library needs, so supervision now runs on opencv-python-headless — or no OpenCV wheel at all — instead of crashing on import. This release also adds Soft-NMS, LabelMe and CreateML dataset formats, GeoTIFF-aware windowed reads for InferenceSlicer, and ships five breaking changes, most notably JSONSink switching to native JSON types and mask_non_max_merge computing exact mask overlap instead of a downscaled approximation. Python 3.9 support is dropped — 3.10 is now the minimum.

✨ Spotlights / highlights

Run supervision without OpenCV

import supervision as sv

window = sv.ImageWindow("frame")
for frame in sv.get_video_frames_generator("input.mp4"):
    window.show(frame)
    if window.wait_key(1) == "q":
        break

The largest change in this release: OpenCV stays the default backend when installed, but supervision no longer requires it. sv.ImageWindow replaces cv2.imshow/cv2.waitKey for display. av>=14.2 is now a required dependency for the PyAV video path during this transition.

Soft-NMS

detections = sv.Detections.from_ultralytics(result)
softened = detections.with_soft_nms(sigma=0.5)
filtered = detections.with_soft_nms(sigma=0.5, score_threshold=0.3)

sv.Detections.with_soft_nms (plus sv.box_soft_non_max_suppression / sv.mask_soft_non_max_suppression) rescales overlapping detections' confidence instead of discarding them outright — useful in crowded scenes where hard NMS drops valid overlapping objects.

New dataset formats + GeoTIFF-aware slicing

dataset = sv.DetectionDataset.from_labelme(
    images_directory_path="images/",
    annotations_directory_path="annotations/",
)

import rasterio

with rasterio.open("RGB.byte.tif") as raster:
    slicer = sv.InferenceSlicer(callback=my_model_callback)
    detections = slicer(raster)

DetectionDataset.from_labelme/as_labelme and from_createml/as_createml join the existing COCO/YOLO/Pascal-VOC converters. sv.InferenceSlicer can now read an open rasterio dataset window-by-window for multi-GB aerial/drone GeoTIFFs without loading the whole image (pip install "supervision[geotiff]"), and accepts batch_size for batched-callback inference.

sv.load_image_from_url

image = sv.load_image_from_url("https://media.roboflow.com/notebooks/examples/dog.jpeg")

Load an image straight from an HTTP(S) URL as an OpenCV array, with optional on-disk caching.

🔄 Migration guide

Five breaking changes. Most require no code changes beyond a type check or threshold recalibration.

sv.JSONSink now emits native JSON types, not strings:

# before 0.30.0
row["score"] == "0.85"  # str
row["is_valid"] == "True"  # str

# after 0.30.0
row["score"] == 0.85  # float
row["is_valid"] is True  # bool

sv.CSVSink stays textual, but its per-row custom-data slicing now matches JSONSink.

sv.mask_non_max_merge computes exact mask overlap, not a downscaled approximation, and ignores the now-deprecated mask_dimension parameter (removal in 0.33.0). Re-tune your overlap threshold after upgrading. overlap_metric is also now keyword-only — most code goes through Detections.with_nmm(...) and is unaffected, but if you call mask_non_max_merge directly and passed overlap_metric positionally, it is now silently swallowed and reverts to OverlapMetric.IOU (no error, wrong results) — pass overlap_metric=... explicitly.

Detections.merge() on mixed dense + CompactMask inputs now returns a CompactMask, not a plain ndarray:

merged = sv.Detections.merge([dense_detections, compact_mask_detections])
isinstance(merged.mask, np.ndarray)  # was True, now False — it's a CompactMask

The all-dense merge path is unchanged. This is also ~2500× less peak memory and ~13× faster on a 1080p frame with 40 detections.

Python 3.10+ is now required — 3.9 reached end-of-life in October 2025.

av>=14.2 is now a required dependency, and opencv-python is capped <6.

Deprecation removals pushed back one release: ByteTrack, supervision.keypoint, normalized_xyxy, and supervision.dataset.utils RLE compatibility shims — originally scheduled for removal in 0.30.0 — are now scheduled for 0.31.0 instead, giving a full transition window.

📝 Notable changes

🚀 Added

• sv.load_image_from_url — load an HTTP(S) image as an OpenCV array, with optional on-disk caching (feat: add image URL loader #2372)
• cv2-free PyAV video fallback + private _cv2 backend facade — image/geometry/drawing/text/video without OpenCV (refactor(cv2): add optional backend facade #2430, feat(cv2): add image fallback backend #2431, feat(cv2): add geometry fallbacks #2432, feat(cv2): add drawing fallbacks #2433, feat(cv2): add Hershey text fallback #2435, feat(video): require PyAV during cv2 transition #2438, feat(cv2): complete fallback integration #2439, refactor(cv2): replace Hershey text with Pillow #2440)
• sv.ImageWindow — tkinter+Pillow desktop window replacing cv2.imshow/cv2.waitKey (feat(utils): add TkImageWindow to unblock switch to opencv-python-headless #2320)
• Soft-NMS — sv.box_soft_non_max_suppression, sv.mask_soft_non_max_suppression, sv.Detections.with_soft_nms (feat: Add soft Non-Max suppression #1624)
• sv.VLM.GOOGLE_GEMINI_3_5 — Detections.from_vlm parses Gemini 3.5 output (feat(vlm): add Gemini 3.5 Flash parsing support #2449)
• get_video_frames_generator(prefetch=...) — background-thread decode into a bounded queue (feat(utils): add prefetch to get_video_frames_generator #2273)
• PolygonZone(require_all_anchors=...) — toggle all-anchors vs. any-anchor containment (feat(detection): add require_all_anchors to PolygonZone #2272)
• KeyPoints.merge() — combine a list of KeyPoints, mirroring Detections.merge (feature: add KeyPoints.merge() method #2412)
• BaseAnnotator.requires_mask — class-level flag on all annotators (feat: declare annotator mask requirements #2370)
• CompactMask.from_coco_rle + Detections.from_inference(compact_masks=True) (feat: add compact RLE mask ingestion #2367)
• CompactMask.image_shape property (perf(detection): keep mixed-mask Detections.merge compact #2383)
• sv.mask_to_roi — exclusive mask-bound helper for slicing/crops (fix: remaining review findings in dataset, docs, and tests #2416)
• DetectionDataset.from_labelme/as_labelme (feat(dataset): add LabelMe format support to DetectionDataset #2299)
• DetectionDataset.from_createml/as_createml (feat(dataset): add CreateML format support to DetectionDataset #2284)
• InferenceSlicer GeoTIFF support — sv.WindowedRasterDataset, pip install "supervision[geotiff]" (feat(detection): support windowed GeoTIFF reads in InferenceSlicer #2281)
• InferenceSlicer(batch_size=...) — batched callback contract (Inference slicer batching #1239)
• show_progress: bool = False on all DetectionDataset load/save methods (feat: add show_progress to dataset load/save operations #2275)
• ConfusionMatrix.benchmark(save_directory_path=...) — adaptive TP/FP/FN validation-mosaic export (Add adaptive TP/FP/FN validation mosaic export #2271)
• HeatMapAnnotator.reset(), TraceAnnotator.reset(), DetectionsSmoother.reset() — clear accumulated per-stream state (fix(annotators): clip crops, fix heatmap wrap, release capture #2393, fix: close out remaining review findings #2418)
• AREA_DATA_FIELD config constant ( fix(metrics): ignore out-of-bucket detections in size-bucketed sco… #2428)
• sv.denormalize_boxes and sv.xyxyxyxy_to_xyxy now exported at the top level

⚠️ Breaking Changes

• Python 3.10+ required — 3.9 dropped (chore: bump minimum Python to 3.10 #2260, chore: update uv.lock to require Python 3.10+ #2381)
• av>=14.2 required; opencv-python capped <6 (feat(video): require PyAV during cv2 transition #2438, ⬆️ Update opencv-python requirement from <5,>=4.5.5.64 to >=4.5.5.64,<6 #2444)
• sv.JSONSink emits native JSON types instead of strings; sv.CSVSink custom-data slicing now matches JSONSink (Fix detection medium review findings #2400)
• sv.mask_non_max_merge computes exact overlap, ignores mask_dimension (Fix detection medium review findings #2400)
• Detections.merge() on mixed dense + CompactMask inputs returns CompactMask (perf(detection): keep mixed-mask Detections.merge compact #2383)

🌱 Changed

• DetectionDataset/ClassificationDataset equality now compares ordered classes lists, not an unordered set (Fix: resolve major complex review #2388, fix: resolve medium dataset findings #2408)
• Deprecation-window delays: ByteTrack, supervision.keypoint, normalized_xyxy, dataset-utils RLE compat removals moved 0.30.0 → 0.31.0 (fix(docs): resolve review deprecation follow-ups #2415)
• Perf: count_nonzero mask pixel counts (perf(detection): count mask pixels with count_nonzero #2361), vectorized box_iou_batch_with_jaccard (perf(detection): vectorize box_iou_batch_with_jaccard #2359), faster mask-annotation ROI blending (Optimize mask annotation ROI blending #2368), fewer corner circles on square label backgrounds (perf(annotators): skip corner circles when drawing square label backgrounds #2346), less compact-mask materialization in the polygon annotator (perf: avoid compact mask materialization in polygon annotator #2369)
• Geometry-aware IoU/area dispatch centralized (refactor: centralize geometry-aware dispatch for detection_area and detection_iou #2374)

🔧 Fixed

• import supervision no longer surfaces the deprecated ByteTrack warning
• Reopening sv.CSVSink/sv.JSONSink starts a fresh session — no stale rows or header (Fix sink state when instances are reopened #2459)
• from_vlm Gemini 2.0/2.5/3.5 salvages valid entries from partially malformed JSON arrays (feat(vlm): add Gemini 3.5 Flash parsing support #2449)
• save_coco_annotations/as_coco read image sizes from headers, no pixel decode for labels-only export (fix: read COCO export image sizes from headers instead of decoding pixels #2442)
• sv.F1Score no longer emits a spurious div-by-zero RuntimeWarning (fix(metrics): avoid division by zero RuntimeWarning in F1Score using np.divide #2437)
• Size-bucketed Precision/Recall/F1Score no longer miscount out-of-bucket detections ( fix(metrics): ignore out-of-bucket detections in size-bucketed sco… #2428, fix: resolve medium dataset findings #2408)
• sv.box_iou_batch upcasts corners to float64, fixing int-dtype overflow (fix: close out remaining review findings #2418)
• from_tensorflow scales boxes by correct axes (fix(detection): scale from_tensorflow boxes by correct axes #2360); from_inference stays aligned on partial masks (fix(detection): keep from_inference aligned on partial masks #2362) and partial tracker_id (fix(detection): do not crash from_inference on partial tracker_id #2353)
• get_anchors_coordinates is OBB-aware (fix(detection): make get_anchors_coordinates OBB-aware #2382)
• Annotator clipping: CropAnnotator ( fix(annotators): clip CropAnnotator boxes to the scene before cropping #2391), HeatMapAnnotator uint8 wrap (fix(annotators): clip crops, fix heatmap wrap, release capture #2393), BackgroundOverlayAnnotator negative coords ( fix(annotators): clip BackgroundOverlayAnnotator boxes to the scene… #2396); get_video_frames_generator releases capture via try/finally (fix(annotators): clip crops, fix heatmap wrap, release capture #2393)
• ByteTrack no longer mutates input Detections; hardened edge cases (fix(tracker): harden ByteTrack edge cases #2413)
• KeyPoints.as_detections accepts numpy/tuple/generator indices (fix(key_points): handle empty and numpy index input, keep degenerate skeletons #2402)
• hex_to_rgba rejects multiple leading # (Fix hex parser accepting multiple leading prefixes #2421); Color(...) validates RGBA range (fix(annotators): resolve annotator medium findings #2407)
• Metrics scoring hardening: greedy matching (fix(metrics): replace np.unique matching with greedy algorithm #2380), COCO 101-point AP, ConfusionMatrix rejects invalid class ids, per-class recall per max-det cutoff, user ignore flags preserved (fix(metrics): harden scoring edge cases #2411); FP counted on empty-GT images (fix(metrics): count false positives on empty-GT images #2397)
• Dataset IO hardening — no caller mutation, class-id validation, optional COCO fields, VOC determinized, basename-collision preflight, RGBA/palette PNG support (fix(dataset): stop split mutation, determinize VOC, guard collisions #2394, fix(dataset): harden dataset IO edge cases #2410, fix: remaining review findings in dataset, docs, and tests #2416)
• Classifications.from_timm softmaxes logits; download_assets verifies MD5 + retries once (fix(utils): normalize timm confidences and verify assets #2414)
• ColorPalette.by_idx() on empty palette raises ValueError not ZeroDivisionError (fix(annotators): resolve annotator medium findings #2407)
• ImageSink.save_image() raises OSError on cv2 write failure (fix: remaining review findings in dataset, docs, and tests #2416)
• Replaced deprecated 2-D np.cross with explicit determinant ( fix: replace deprecated 2-D np.cross with explicit determinant #2386); removed defensive asserts in image annotators (Refactor/remove asserts annotators image #2354)
• cv2-free fallback correctness fixes across border/blend/polygon/text/color operations (feat(cv2): add image fallback backend #2431, feat(cv2): add drawing fallbacks #2433, feat(cv2): complete fallback integration #2439, refactor(cv2): replace Hershey text with Pillow #2440, perf(cv2): simplify fallback operations #2441)

---

🏆 Contributors

• Abhijith Neil Abraham (@abhijithneilabraham, LinkedIn) — added KeyPoints.merge(); fixed out-of-bucket metric scoring and key_points edge cases
• Agis Kounelis (@kounelisagis, LinkedIn) — made get_anchors_coordinates OBB-aware; annotator/perf fixes
• Andrew Barnes (@Bortlesboat, LinkedIn) — fixed sink state on reopen
• Dylan Parsons (@dylanparsons, LinkedIn) — converted Detections doctests to runnable examples
• Erik (@Erol444) — added sv.load_image_from_url
• HALLOUARD (@YHallouard, LinkedIn) — added Soft-NMS
• Lee Clement (@leeclemnet, LinkedIn) — fixed COCO export to read image sizes from headers
• Linas Kondrackis (@LinasKo, LinkedIn) — added batching to InferenceSlicer
• Madhav-C (@madhavcodez, LinkedIn) — added LabelMe and CreateML dataset formats, GeoTIFF InferenceSlicer support
• Mahbod (@Ace3Z) — added prefetch to get_video_frames_generator, require_all_anchors to PolygonZone
• Matt Van Horn (@mvanhorn, LinkedIn) — centralized geometry-aware IoU/area dispatch
• Murillo Rodrigues (@murillo-ro-silva, LinkedIn) — added show_progress to dataset load/save
• Nick Herrig (@NickHerrig, LinkedIn) — added the face-blurring cookbook
• Piotr Skalski (@SkalskiP, LinkedIn) — added Gemini 3.5 Flash VLM support
• Ruben Haisma (@RubenHaisma, LinkedIn) — perf fixes across mask counting, box IoU, from_tensorflow
• Saif Khan (@K-saif, LinkedIn) — added the adaptive TP/FP/FN validation mosaic export
• shao (@shaoming11, LinkedIn) — improved draw/utils.py doctests
• Shehzad Waseem (@Shehzad3684) — fixed a division-by-zero warning in F1Score
• Teïlo M (@teilomillet) — fixed the hex parser accepting multiple leading prefixes
• Vikas saini (@vikassaini77, LinkedIn) — converted fenced examples to doctests; removed defensive asserts in annotators
• Jirka Borovec (@Borda) — built the cv2-free OpenCV-optional backend (image, geometry, drawing, text, and PyAV video fallback) end to end, plus various hardening fixes across detection, dataset, and metrics modules; release maintainer

---

Full changelog: 0.29.1...0.30.0

[Borda]

Still waiting on #2443

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87%. Comparing base (541b022) to head (fd7c199).

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #2462   +/-   ##
=======================================
  Coverage       87%     87%           
=======================================
  Files           85      85           
  Lines        12021   12021           
=======================================
  Hits         10424   10424           
  Misses        1597    1597           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.