chore: bump minimum Python to 3.10

.github/copilot-instructions.md

@@ -8,7 +8,7 @@ This file provides context-aware guidance for GitHub Copilot when working in the
 
 **Supervision** is a Python library providing reusable computer vision utilities for working with object detection models (YOLO, SAM, etc.). It offers tools for detections processing, tracking, annotation, and dataset management.
 
-- **Languages**: Python 3.9+
+- **Languages**: Python 3.10+
 - **Key Dependencies**: NumPy, OpenCV, SciPy
 - **License**: MIT
 

.github/workflows/ci-tests.yml

@@ -29,7 +29,7 @@ jobs:
       fail-fast: false
       matrix:
         os: ["ubuntu-latest", "windows-latest", "macos-latest"]
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     runs-on: ${{ matrix.os }}
     steps:
       - name: 📥 Checkout the repository

README.md

@@ -38,7 +38,7 @@
 ## 💻 install
 
 Pip install the supervision package in a
-[**Python>=3.9**](https://www.python.org/) environment.
+[**Python>=3.10**](https://www.python.org/) environment.
 
 ```bash
 pip install supervision

docs/changelog.md

@@ -5,7 +5,13 @@ date_modified: 2026-04-30
 
 # Changelog
 
-### UnReleased
+### UnReleased <small>upcoming</small>
+
+!!! failure "Python 3.9 Support Terminated"
+
+    With the `supervision-0.29.0` release, we are terminating official support for Python 3.9, which reached end-of-life in October 2025. The minimum supported Python version is now **3.10**.
+
+    Users on Python 3.9 should upgrade their environment before updating supervision.
 
 - Added [#2267](https://github.com/roboflow/supervision/pull/2267): [`DetectionDataset.as_coco`](https://supervision.roboflow.com/latest/datasets/core/#supervision.dataset.core.DetectionDataset.as_coco) and `save_coco_annotations` now accept `starting_image_id` and `starting_annotation_id` parameters (both default to `1`, preserving existing behavior) and return a `(next_image_id, next_annotation_id)` tuple. Feed the returned values into the next split's call to produce globally unique COCO ids across train/valid/test exports. Fixes id collisions reported in [#768](https://github.com/roboflow/supervision/issues/768). **Note**: the return type changes from `None` to `tuple[int, int]` — callers that assert `result is None` must be updated.
 

examples/compact_mask/benchmark.py

@@ -20,11 +20,11 @@
 import math
 import time
 import tracemalloc
+from collections.abc import Callable
 from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Callable
 
 import cv2
 import numpy as np

examples/count_people_in_zone/inference_example.py

@@ -135,7 +135,7 @@ def main(
     target_video_path: str | None = None,
     confidence_threshold: float = 0.3,
     iou_threshold: float = 0.7,
-):
+) -> None:
     """
     Counting people in zones with Inference and Supervision.
 

examples/count_people_in_zone/ultralytics_example.py

@@ -133,7 +133,7 @@ def main(
     target_video_path: str | None = None,
     confidence_threshold: float = 0.3,
     iou_threshold: float = 0.7,
-):
+) -> None:
     """
     Counting people in zones with YOLO and Supervision.
 

examples/heatmap_and_track/script.py

@@ -1,123 +1,121 @@
-from typing import Optional
-
-import cv2
-from ultralytics import YOLO
-
-import supervision as sv
-from supervision.assets import VideoAssets, download_assets
-
-
-def download_video() -> str:
-    download_assets(VideoAssets.PEOPLE_WALKING)
-    return VideoAssets.PEOPLE_WALKING.value
-
-
-def main(
-    source_weights_path: str,
-    source_video_path: Optional[str] = None,
-    target_video_path: str = "output.mp4",
-    confidence_threshold: float = 0.35,
-    iou_threshold: float = 0.5,
-    heatmap_alpha: float = 0.5,
-    radius: int = 25,
-    track_activation_threshold: float = 0.35,
-    track_seconds: int = 5,
-    minimum_matching_threshold: float = 0.99,
-) -> None:
-    """
-    Heatmap and Tracking with Supervision.
-
-    Args:
-        source_weights_path: Path to the source weights file
-        source_video_path: Path to the source video file
-        target_video_path: Path to the target video file
-        confidence_threshold: Confidence threshold for the model
-        iou_threshold: IOU threshold for the model
-        heatmap_alpha: Opacity of the overlay mask, between 0 and 1
-        radius: Radius of the heat circle
-        track_activation_threshold: Detection confidence threshold for track activation
-        track_seconds: Number of seconds to buffer when a track is lost
-        minimum_matching_threshold: Threshold for matching tracks with detections
-    """
-    ### instantiate model
-    model = YOLO(source_weights_path)
-    source_video_path = source_video_path or download_video()
-
-    ### heatmap config
-    heat_map_annotator = sv.HeatMapAnnotator(
-        position=sv.Position.BOTTOM_CENTER,
-        opacity=heatmap_alpha,
-        radius=radius,
-        kernel_size=25,
-        top_hue=0,
-        low_hue=125,
-    )
-
-    ### annotation config
-    label_annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
-
-    ### get the video fps
-    cap = cv2.VideoCapture(source_video_path)
-    fps = int(cap.get(cv2.CAP_PROP_FPS))
-    cap.release()
-
-    ### tracker config
-    byte_tracker = sv.ByteTrack(
-        track_activation_threshold=track_activation_threshold,
-        lost_track_buffer=track_seconds * fps,
-        minimum_matching_threshold=minimum_matching_threshold,
-        frame_rate=fps,
-    )
-
-    ### video config
-    video_info = sv.VideoInfo.from_video_path(video_path=source_video_path)
-    frames_generator = sv.get_video_frames_generator(
-        source_path=source_video_path, stride=1
-    )
-
-    ### Detect, track, annotate, save
-    with sv.VideoSink(target_path=target_video_path, video_info=video_info) as sink:
-        for frame in frames_generator:
-            result = model(
-                source=frame,
-                classes=[0],  # only person class
-                conf=confidence_threshold,
-                iou=iou_threshold,
-                # show_conf = True,
-                # save_txt = True,
-                # save_conf = True,
-                # save = True,
-                device=None,  # use None = CPU, 0 = single GPU, or [0,1] = dual GPU
-            )[0]
-
-            detections = sv.Detections.from_ultralytics(result)  # get detections
-
-            detections = byte_tracker.update_with_detections(
-                detections
-            )  # update tracker
-
-            ### draw heatmap
-            annotated_frame = heat_map_annotator.annotate(
-                scene=frame.copy(), detections=detections
-            )
-
-            ### draw other attributes from `detections` object
-            labels = [
-                f"#{tracker_id}"
-                for class_id, tracker_id in zip(
-                    detections.class_id, detections.tracker_id
-                )
-            ]
-
-            label_annotator.annotate(
-                scene=annotated_frame, detections=detections, labels=labels
-            )
-
-            sink.write_frame(frame=annotated_frame)
-
-
-if __name__ == "__main__":
-    from jsonargparse import auto_cli, set_parsing_settings
-
-    set_parsing_settings(parse_optionals_as_positionals=True)
-    auto_cli(main, as_positional=False)
+import cv2
+from ultralytics import YOLO
+
+import supervision as sv
+from supervision.assets import VideoAssets, download_assets
+
+
+def download_video() -> str:
+    download_assets(VideoAssets.PEOPLE_WALKING)
+    return VideoAssets.PEOPLE_WALKING.value
+
+
+def main(
+    source_weights_path: str,
+    source_video_path: str | None = None,
+    target_video_path: str = "output.mp4",
+    confidence_threshold: float = 0.35,
+    iou_threshold: float = 0.5,
+    heatmap_alpha: float = 0.5,
+    radius: int = 25,
+    track_activation_threshold: float = 0.35,
+    track_seconds: int = 5,
+    minimum_matching_threshold: float = 0.99,
+) -> None:
+    """
+    Heatmap and Tracking with Supervision.
+
+    Args:
+        source_weights_path: Path to the source weights file
+        source_video_path: Path to the source video file
+        target_video_path: Path to the target video file
+        confidence_threshold: Confidence threshold for the model
+        iou_threshold: IOU threshold for the model
+        heatmap_alpha: Opacity of the overlay mask, between 0 and 1
+        radius: Radius of the heat circle
+        track_activation_threshold: Detection confidence threshold for track activation
+        track_seconds: Number of seconds to buffer when a track is lost
+        minimum_matching_threshold: Threshold for matching tracks with detections
+    """
+    ### instantiate model
+    model = YOLO(source_weights_path)
+    source_video_path = source_video_path or download_video()
+
+    ### heatmap config
+    heat_map_annotator = sv.HeatMapAnnotator(
+        position=sv.Position.BOTTOM_CENTER,
+        opacity=heatmap_alpha,
+        radius=radius,
+        kernel_size=25,
+        top_hue=0,
+        low_hue=125,
+    )
+
+    ### annotation config
+    label_annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
+
+    ### get the video fps
+    cap = cv2.VideoCapture(source_video_path)
+    fps = int(cap.get(cv2.CAP_PROP_FPS))
+    cap.release()
+
+    ### tracker config
+    byte_tracker = sv.ByteTrack(
+        track_activation_threshold=track_activation_threshold,
+        lost_track_buffer=track_seconds * fps,
+        minimum_matching_threshold=minimum_matching_threshold,
+        frame_rate=fps,
+    )
+
+    ### video config
+    video_info = sv.VideoInfo.from_video_path(video_path=source_video_path)
+    frames_generator = sv.get_video_frames_generator(
+        source_path=source_video_path, stride=1
+    )
+
+    ### Detect, track, annotate, save
+    with sv.VideoSink(target_path=target_video_path, video_info=video_info) as sink:
+        for frame in frames_generator:
+            result = model(
+                source=frame,
+                classes=[0],  # only person class
+                conf=confidence_threshold,
+                iou=iou_threshold,
+                # show_conf = True,
+                # save_txt = True,
+                # save_conf = True,
+                # save = True,
+                device=None,  # use None = CPU, 0 = single GPU, or [0,1] = dual GPU
+            )[0]
+
+            detections = sv.Detections.from_ultralytics(result)  # get detections
+
+            detections = byte_tracker.update_with_detections(
+                detections
+            )  # update tracker
+
+            ### draw heatmap
+            annotated_frame = heat_map_annotator.annotate(
+                scene=frame.copy(), detections=detections
+            )
+
+            ### draw other attributes from `detections` object
+            labels = [
+                f"#{tracker_id}"
+                for class_id, tracker_id in zip(
+                    detections.class_id, detections.tracker_id
+                )
+            ]
+
+            label_annotator.annotate(
+                scene=annotated_frame, detections=detections, labels=labels
+            )
+
+            sink.write_frame(frame=annotated_frame)
+
+
+if __name__ == "__main__":
+    from jsonargparse import auto_cli, set_parsing_settings
+
+    set_parsing_settings(parse_optionals_as_positionals=True)
+    auto_cli(main, as_positional=False)

examples/speed_estimation/inference_example.py

@@ -44,7 +44,7 @@ def main(
     roboflow_api_key: str | None = None,
     confidence_threshold: float = 0.3,
     iou_threshold: float = 0.7,
-):
+) -> None:
     """
     Vehicle Speed Estimation using Inference and Supervision.
 

examples/speed_estimation/ultralytics_example.py

@@ -41,7 +41,7 @@ def main(
     target_video_path: str,
     confidence_threshold: float = 0.3,
     iou_threshold: float = 0.7,
-):
+) -> None:
     """
     Vehicle Speed Estimation using Ultralytics and Supervision.
 

examples/speed_estimation/yolo_nas_example.py

@@ -42,7 +42,7 @@ def main(
     target_video_path: str,
     confidence_threshold: float = 0.3,
     iou_threshold: float = 0.7,
-):
+) -> None:
     """
     Vehicle Speed Estimation using YOLO-NAS and Supervision.
 

examples/time_in_zone/inference_stream_example.py

@@ -15,7 +15,7 @@
 
 
 class CustomSink:
-    def __init__(self, zone_configuration_path: str, classes: list[int]):
+    def __init__(self, zone_configuration_path: str, classes: list[int]) -> None:
         self.classes = classes
         self.tracker = sv.ByteTrack(minimum_matching_threshold=0.5)
         self.fps_monitor = sv.FPSMonitor()

examples/time_in_zone/rfdetr_file_example.py

@@ -25,7 +25,7 @@ class ModelSize(Enum):
     LARGE = "large"
 
     @classmethod
-    def list(cls):
+    def list(cls) -> list[str]:
         return list(map(lambda c: c.value, cls))
 
     @classmethod
@@ -44,7 +44,9 @@ def from_value(cls, value: ModelSize | str) -> ModelSize:
         )
 
 
-def load_model(checkpoint: ModelSize | str, device: str, resolution: int):
+def load_model(
+    checkpoint: ModelSize | str, device: str, resolution: int
+) -> RFDETRBase | RFDETRLarge | RFDETRMedium | RFDETRNano | RFDETRSmall:
     checkpoint = ModelSize.from_value(checkpoint)
 
     if checkpoint == ModelSize.NANO:

examples/time_in_zone/rfdetr_naive_stream_example.py

@@ -25,7 +25,7 @@ class ModelSize(Enum):
     LARGE = "large"
 
     @classmethod
-    def list(cls):
+    def list(cls) -> list[str]:
         return list(map(lambda c: c.value, cls))
 
     @classmethod
@@ -44,7 +44,9 @@ def from_value(cls, value: ModelSize | str) -> ModelSize:
         )
 
 
-def load_model(checkpoint: ModelSize | str, device: str, resolution: int):
+def load_model(
+    checkpoint: ModelSize | str, device: str, resolution: int
+) -> RFDETRBase | RFDETRLarge | RFDETRMedium | RFDETRNano | RFDETRSmall:
     checkpoint = ModelSize.from_value(checkpoint)
 
     if checkpoint == ModelSize.NANO: