Guide · Open source

How to use supervision: install, load datasets and annotate

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Supervision is an open-source Python library from Roboflow for computer vision projects. It provides ready-made tools for common chores around a detection or segmentation model: loading and converting datasets, drawing boxes and labels, and counting objects in zones. This guide shows how to install it and use its main parts, so you can get a working script running.

supervisionroboflow/supervision · ★ 51.5k · MIT Install options & downloads

Quick start

1Check your Python version. Confirm you have Python 3.10 or newer, since the README lists this as the requirement.
2Install the package. Run pip install supervision inside your Python environment.
3Load a dataset. Use sv.DetectionDataset.from_coco, from_yolo or from_pascal_voc with the paths to your images and annotations.
4Get detections. Run a detection model you already have, or use a connector such as Ultralytics, Transformers, MMDetection or Inference, to produce sv.Detections.
5Annotate the image. Create a BoxAnnotator, then call annotate with a copy of your image and the detections.
6Save or convert. Use the as_coco, as_yolo or as_pascal_voc method to write the dataset in another format.

Install supervision with pip

Supervision is installed with pip. The README asks for Python 3.10 or newer, so check your Python version first and install the package inside that environment.

Requires Python 3.10 or newer
The README also points to a guide covering conda, mamba and installing from source

pip install supervision

Connect your detection model

Supervision is designed to be model agnostic. You can plug in any classification, detection or segmentation model. The README lists connectors for Ultralytics, Transformers, MMDetection and Inference, and notes that some integrations such as rfdetr already return sv.Detections directly.

The README example uses rfdetr and Pillow, which you install with pip install pillow rfdetr. It then calls model.predict on an image and counts the results. Replace the image path with your own file.

Connectors are listed for Ultralytics, Transformers, MMDetection and Inference
Inference requires a Roboflow API key, according to the README

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)

len(detections)

Draw boxes on an image with annotators

Annotators draw visual output on top of your image. The README shows BoxAnnotator, which takes a scene and a set of detections and returns an annotated frame. The README also says annotators are highly customizable, so you can change how the result looks for your use case.

The example below assumes you already have detections from a model. It uses OpenCV to read the image, which is a separate package from supervision.

BoxAnnotator draws bounding boxes
Pass a copy of the image as the scene so the original stays unchanged

import cv2
import supervision as sv

image = cv2.imread("path/to/image.jpg")
# Assuming detections are obtained from a model
detections = sv.Detections(...)

box_annotator = sv.BoxAnnotator()
annotated_frame = box_annotator.annotate(scene=image.copy(), detections=detections)

Load, split and merge datasets

Supervision includes utilities to load, split, merge and save datasets in the supported formats. The README names COCO, YOLO and Pascal VOC. The example below loads a COCO training split from a Roboflow export. Replace WORKSPACE_ID, PROJECT_ID and PROJECT_VERSION with your own values.

Loading is lazy: the README notes that images load on demand when you index or iterate the dataset. Splitting takes a split_ratio, and merge combines datasets and their class lists.

from_coco, from_yolo and from_pascal_voc load datasets
split(split_ratio=...) divides a dataset
DetectionDataset.merge combines several datasets
as_coco, as_yolo and as_pascal_voc save a dataset in each format

import supervision as sv
from roboflow import Roboflow

project = Roboflow().workspace("WORKSPACE_ID").project("PROJECT_ID")
dataset = project.version("PROJECT_VERSION").download("coco")

ds = sv.DetectionDataset.from_coco(
    images_directory_path=f"{dataset.location}/train",
    annotations_path=f"{dataset.location}/train/_annotations.coco.json",
)

path, image, annotation = ds[0]

Convert a dataset between formats

To convert a dataset, load it in one format and save it in another. The README gives a YOLO to Pascal VOC example that chains from_yolo with as_pascal_voc. Fill in the directory placeholders with your own paths.

Use the same chain pattern for other supported pairs

sv.DetectionDataset.from_yolo(
    images_directory_path=...,
    annotations_directory_path=...,
    data_yaml_path=...,
).as_pascal_voc(
    images_directory_path=...,
    annotations_directory_path=...,
)

What people use it for

Drawing bounding boxes on frames from a detection model for a demo app
Converting a YOLO dataset to Pascal VOC before training with another tool
Merging two labelled datasets that share classes into one dataset
Counting objects in zones for a video analytics demo, as the README describes real-time zone counting

Frequently asked questions

Is supervision free to use?

The repository is released under the MIT licence, as shown in the README badge and project details. Check the LICENSE.md file in the repository for the full terms.

What Python version does supervision need?

The README asks for Python 3.10 or newer. Install it in an environment that uses that version or later.

How do I install supervision?

Run pip install supervision in a Python 3.10+ environment. The README also links to a guide for conda, mamba and installing from source.

Does supervision include a trained model?

No. The README covers connecting models you already have, such as Ultralytics, Transformers or MMDetection models. It does not provide a model of its own.

Which dataset formats does supervision support?

The README names COCO, YOLO and Pascal VOC, with load, save and convert methods for each. It is a code library, so these are used from Python.

How is supervision different from OpenCV or Ultralytics?

Supervision focuses on shared helpers around a detection model, such as annotators, dataset utilities and zone counting. OpenCV is a general image library, and Ultralytics is a model framework; the two can be used alongside supervision.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Supervision suits Python developers who already run object detection or segmentation models and want ready-made code for drawing results, handling datasets and counting in zones. It is not a point-and-click app, and it does not include a trained model, so non-programmers or users without Python 3.10 should choose a different tool.

Install options & downloads