yolov7-object-tracking: A Demo Wrapper That Pairs YOLO Detection With Sort

The gap this repository fills

Detection and tracking are two separate problems, and most tutorials solve only the first. A detector tells you where objects are in a single frame. It has no memory. Run it on frame 400 and frame 401 and you get two independent lists of boxes with no link between them. Anything downstream that needs to count people crossing a line, measure time in frame, or follow one object through a scene requires that link.

This repository exists to close that gap with a small amount of glue. The README describes it as "YOLOv7 Object Tracking Using PyTorch, OpenCV and Sort Tracking", and the two entry points reflect that split: detect.py for detection alone, detect_and_track.py for detection plus tracking. The audience is someone who wants to see boxes with persistent numeric IDs on a video file or a camera feed without assembling a pipeline from scratch. That is a demo-shaped goal, and the repository is honest about it.

How detection and Sort are wired together

The architecture is a per-frame loop, not a service. Each frame goes through the YOLO model to produce bounding boxes and class scores. Those boxes are then handed to Sort, which is a tracking-by-detection algorithm. Sort does not look at pixels at all. It takes the box list from the current frame, predicts where each existing track should be using a motion model, and matches predictions to new detections by overlap. The README's argument table lists --iou-thres with a default of 0.45 described as the "Intersection over Union (IoU) threshold for NMS", so the overlap threshold you set also shapes which detections survive before tracking sees them.

The consequence of this design is that track identity lives entirely in Sort's internal state. If the detector misses an object for enough consecutive frames, the track has nothing to match against and the ID is gone. When the object reappears, it gets a new number. This is a property of tracking-by-detection with a motion-only model, not a bug in the wrapper, but it is the behaviour you will notice first on real footage. The README does not document a maximum-age or track-buffer parameter, so that behaviour is not tunable from the command line as far as the supplied material shows.

Getting it running: clone, environment, two scripts

The README gives a complete setup path. Clone the repository, then cd yolov7-object-tracking. Create an environment with conda create -n yolov7objtracking python=3.12, or use python3 -m venv yolov7objtracking with the activate step for your platform. Then pip install --upgrade pip followed by pip install -r requirements.txt.

From there the commands are short. Detection only: python detect.py --weights yolov7.pt. Tracking: python detect_and_track.py --weights yolov7.pt. The README states that pretrained yolov7.pt weights are downloaded automatically if needed. For your own footage, add --source "your video.mp4". For a webcam, --source 0; for a second camera, --source 1. For a network feed, the README shows --source "your IP Camera Stream URL" --device 0. To limit tracking to one class, --classes 0 selects person. --colored-trk switches on coloured tracks, and --save-txt --save-bbox-dim writes centroids, IDs, and box coordinates to text. Output lands in runs/detect/obj-tracking under the original filename.

The repository also states that YOLOv8 is supported through the same script, with python detect.py --weights yolov8n.pt given as the example. YOLOv9 through YOLO13 are listed as coming soon, which is a statement of intent rather than a shipped capability.

Where the wrapper stops being enough

The most important limitation is the one implied by the dependency list rather than stated in the README. Sort is a motion-only tracker. It has no appearance model, so it cannot re-identify an object after an occlusion or a miss. Two people walking past each other in similar clothing are a hard case for overlap-based matching, and the README offers no parameter to address it. If your application needs stable identity across gaps, this repository is the wrong tool and no amount of flag tuning will change that.

The second limitation is scope. This is a script collection with a single dated release, yolov7-object-tracking from 2022-08-21. The README lists YOLOv9 through YOLO13 as "coming soon", and the last push is 2026-08-24, so the repository is alive but the tracking core has not been swapped. There is no documented API surface, no library import path, and no configuration file. Everything is command-line arguments. Integrating it into a larger application means either shelling out to the script or copying the loop into your own code, and the README gives no guidance on which is intended.

Third, the argument table in the supplied README is truncated at --save-conf, so the full flag set is not verifiable from this material. Treat any flag not listed here as unconfirmed.

What you would use instead, and why the difference matters

The obvious alternative is the Ultralytics tracking stack, which the README itself points at by adding YOLOv8 support through the same detect.py entry point. The difference is architectural rather than cosmetic. Ultralytics ships tracking as part of the same package that runs detection, exposes the tracker as a configuration option, and supports trackers beyond Sort, including ones that use appearance features. That means occlusion handling is a configuration decision rather than a rewrite.

The trade-off is dependency weight and licence. Pulling the Ultralytics package brings a larger surface area and its own AGPL-3.0 terms, which is the same licence family this repository uses. If you want a permissive licence, neither option is a fit, and you would be looking at a separately licensed detector plus a separately licensed tracker, assembled yourself. That is more work, and it is the honest cost of avoiding copyleft. If you only need detection with no identity persistence, plain detect.py here or any standalone YOLO inference script is sufficient and the tracking code is dead weight.

Maintenance cost and the licence question

The repository carries a CI workflow and a codecov badge, so there is some automated checking, but the supplied material does not describe a test suite, a release cadence, or a deprecation policy. One dated release and a stream of "coming soon" model versions suggests the maintenance model is periodic catch-up rather than continuous development. If you depend on it, expect to pin your own versions of torch and opencv from requirements.txt and to test upgrades yourself, because the README does not document compatibility ranges beyond the Python 3.12 environment it recommends.

The licence is AGPL-3.0. That is a strong copyleft licence with a network-use clause. Running a modified version as a network service can trigger source disclosure obligations. Whether that applies to your deployment depends on facts I cannot assess here, and this is not legal advice. What I can say plainly is that AGPL-3.0 is incompatible with closed-source distribution in the ordinary case, so if this code is destined for a proprietary product, resolve that question before writing integration code, not after.

Who should pick this up, and what to check first

This is a reasonable starting point for a prototype, a classroom exercise, or an internal demo where you need boxes and IDs on a video today and you are willing to accept ID switches. The setup is short, the two scripts are easy to read, and the output directory convention means you can inspect results without writing any code.

It is the wrong choice for production identity tracking, for anything requiring re-identification after occlusion, and for any closed-source deployment where AGPL-3.0 is a blocker. The gap between "boxes with numbers" and "reliable tracks" is exactly where this repository stops, and the documentation does not pretend otherwise.

The concrete first step is to run detect_and_track.py --weights yolov7.pt --source "your video.mp4" --save-txt --save-bbox-dim on a clip you already know well, then open the text output in runs/detect/obj-tracking and count how many times an ID changes on a single object. That count, not the README, tells you whether this repository fits your problem.

Editorial conclusion

Adopt it if you need a working detection-plus-Sort loop on video today and you are comfortable with AGPL-3.0 obligations. Do not adopt it if you need identity persistence through occlusion, a maintained tracking core, or permissive licensing for a closed product. Before committing, run detect_and_track.py on a clip with crossings and occlusions, check the ID switches in the saved output under runs/detect/obj-tracking, and confirm with your legal contact whether AGPL-3.0 fits your distribution model.

Official sources

1. Issues
2. License: AGPL-3.0
3. README
4. Releases
5. RizwanMunawar/yolov7-object-tracking on GitHub