Supervision: Computer Vision Library for Detections

An Essential Computer Vision Toolkit

Supervision is an open-source Python package with reusable building blocks for computer vision: model connectors, customizable annotators for drawing boxes and masks, and dataset utilities for COCO, YOLO, and Pascal VOC. It doesn't train or ship models itself — it standardizes the `sv.Detections` object that sits between whatever model you run and the annotation code you write on top.

Installing the Supervision Library

Installing Supervision is one command: `pip install supervision`. The README specifies a Python 3.10 or newer environment for that install — there's no stated support for older Python 3.x releases. If you'd rather use conda, mamba, or install from source, the README doesn't walk through those steps itself; it links out to a separate guide on Roboflow's documentation site instead, so the pip path is the only one this repo's own README documents in full.

Practical Code Examples

The core workflow is: run your own detection or segmentation model, wrap its output in `sv.Detections`, then hand that to an annotator. Some models return that format directly — the README's example uses `rfdetr`'s `RFDETRSmall`: ```python import supervision as sv from PIL import Image from rfdetr import RFDETRSmall image = Image.open("path/to/image.jpg") model = RFDETRSmall() detections = model.predict(image, threshold=0.5) ``` For models that don't return `sv.Detections` natively, Supervision ships connectors — the README names Ultralytics, Transformers, MMDetection, and Roboflow's own Inference service as examples, with Inference specifically requiring a Roboflow API key to call. Once you have a `Detections` object, drawing it onto a frame is short: `sv.BoxAnnotator().annotate(scene=image.copy(), detections=detections)`. The same pattern extends to datasets — `sv.DetectionDataset.from_coco(...)` loads a COCO-format dataset, and calling `.split(split_ratio=0.7)` on the result divides it into train/test sets without a custom script.

Real-world Application Examples

• •Zone dwell-time analysis — the README's own tutorial pairs detection and tracking to measure how long objects sit inside a defined zone, aimed at retail or traffic scenarios.
• •Vehicle speed estimation — another README tutorial chains YOLO, ByteTrack, and Roboflow Inference together with a perspective transform to estimate vehicle speed from video, an example of the detection tracking Supervision is built around.
• •Reformatting a dataset for a new training framework — converting an existing COCO or Pascal VOC dataset to YOLO format (or back) using `DetectionDataset`'s `as_yolo`/`as_coco`/`as_pascal_voc` methods instead of writing a converter yourself, useful for data labeling handoffs between tools.
• •Swapping detection models mid-project — moving from an Ultralytics model to an Inference-hosted one without rewriting the annotation and video analysis code downstream, since both funnel into the same `sv.Detections` object.

Other Computer Vision Libraries

Common Questions

Key features

• ✓Model-agnostic detections — connectors normalize output from Ultralytics, Transformers, MMDetection, and Roboflow Inference into one `sv.Detections` object; some libraries, like `rfdetr`, already return that format directly.
• ✓Customizable annotators — an image annotation tool built into the library; `BoxAnnotator` and similar classes draw detections onto a frame in a couple of lines instead of hand-rolled OpenCV drawing calls.
• ✓Dataset utilities — `DetectionDataset` loads, splits, merges, saves, and converts between COCO, YOLO, and Pascal VOC without a separate object detection library or custom parser.
• ✓Tracking and video-processing support — the repo's own GitHub topics list tracking and video-processing alongside detection, classification, and instance-segmentation.
• ✓MIT license — free to embed in commercial deep learning utilities without copyleft strings attached.
• ✓Hacktoberfest-tagged and actively maintained by Roboflow, with a public contributing guide for outside PRs.

The problem it solves

Swap a YOLO model for a Transformers-based detector, or move a dataset from Pascal VOC to COCO, and normally every downstream script — annotation, filtering, dataset splitting — has to be rewritten around the new output shape. That's the specific friction in Python machine learning vision projects that stitch together a detector, a tracker, and a training pipeline from separate libraries: each one returns detections in its own shape. Supervision's `sv.Detections` object and dataset utilities give that downstream code one interface to target, so the model or the dataset format underneath can change without touching the annotation and evaluation code built on top of it.

Who should try it — and who should skip

Try Supervision if you're already writing a Python computer vision pipeline by hand and want annotation, tracking-adjacent, and dataset-conversion code you don't have to maintain yourself — especially useful once you're bouncing between different model libraries and rewriting a translator for each one's output shape. Skip it if you're running a one-off script against a single model's native output, or you're stuck on a pre-3.10 Python interpreter you can't upgrade; the extra abstraction isn't worth adding for a script you'll run once.

Related repositories