YOLOv9

Install

YOLOv9 needs no extra beyond the base package.

pip install libreyolo

Predict

Weights download from Hugging Face on first use and are cached locally.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9s.pt")result = model(SAMPLE_IMAGE, save=True) for box in result.boxes:    print(box.cls, box.conf, box.xyxy)

libreyolo predict model=LibreYOLO9s.pt save=True \  source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg

from libreyolo import LibreYOLO, SAMPLE_IMAGE # Same call, different checkpoint. The end-to-end head returns its own# top-scoring predictions, so no NMS runs and iou is ignored.model = LibreYOLO("LibreYOLO9E2Es.pt")result = model(SAMPLE_IMAGE, conf=0.25, max_det=300) print(len(result.boxes))

The returned Results object is the one every family returns, so swapping in a different detector is a one line change. On the base and stride-4 models, conf sets the confidence threshold and iou the NMS threshold. The end-to-end model runs no NMS and ignores iou, so conf and max_det are what shape its output. See prediction for sources, streaming and result handling.

Variants

Three variants share a backbone. All three detect only, and they take the same arguments.

The base model predicts on three feature scales and clears duplicate boxes with NMS.

The end-to-end model keeps that head and adds a one-to-one matching branch beside it. Inference reads the one-to-one branch alone and takes its top-scoring predictions, so no NMS runs. Choose it when the runtime you deploy to has no NMS operator.

The stride-4 model surfaces one level further up the backbone, extends the neck down to it and predicts on four scales instead of three. The extra scale is for objects that cover few pixels; the one published checkpoint for it is trained on aerial imagery. Base detection checkpoints transfer into it: the backbone and neck load unchanged, the three pretrained head towers shift up one slot, and the stride-4 tower starts from random initialization.

Train

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt")model.train(data="my-dataset.yaml", epochs=100, imgsz=640, batch=16)

libreyolo train model=LibreYOLO9s.pt data=my-dataset.yaml \  epochs=100 imgsz=640 batch=16

from libreyolo import LibreYOLO9P2 # The stride-4 variant has no COCO checkpoint of its own, so name a# base detection one: its backbone and neck load unchanged and the# stride-4 head tower starts from random initialization.model = LibreYOLO9P2(None, size="s")model.train(data="my-dataset.yaml", epochs=100, pretrained="LibreYOLO9s.pt")

pretrained decides what the run starts from. Pass True to load the published checkpoint for the same model and size, or a name or path for anything else. Tensors whose shape does not match are skipped rather than refused, and the run logs how many loaded, so a checkpoint trained on a different class count is still a usable starting point.

The stride-4 model has no published COCO checkpoint of its own, so True resolves there to a file that does not exist and the download fails. Name a base detection checkpoint instead.

See training for datasets, augmentation, multi-GPU and loggers.

The base model can train a PGI auxiliary branch next to its main head. The branch is training-only: prediction and export use the main head. A run attaches it when the starting weights carry PGI tensors or when it trains from scratch. The published base checkpoints carry none, so a fine-tune from them trains the main head only and logs that. aux_weight=0.25 attaches a new branch at that loss weight anyway, and aux_weight=0 keeps it off. A resumed run keeps its checkpoint's PGI setup. On the m and c sizes the branch is the upstream one: a second backbone on the input image, whose stages CBFuse sums with CBLinear taps of the main backbone, and its own head, 12.8M and 25.7M training-only parameters at 80 classes. The end-to-end and stride-4 models have no PGI branch.

All three variants clip the gradient L2 norm at 10 before each optimizer step; clip_max_norm=0 turns clipping off. Label assignment scores anchors in fp32, also under float16 autocast. max_labels=300 caps the boxes kept per training image, and boxes past it are dropped with a one-time warning; assignment memory follows each image's real boxes, not the cap. SGD momentum warms from 0.8 to 0.937 over three epochs. letterbox_pad=None inherits the checkpoint stamp: unmarked weights use topleft, while new official conversions record center.

YOLO9 and YOLOX mosaic prefer annotated partners with at most 20 draws; YOLO9 MixUp uses the same policy. MixUp is off by default (mixup_prob=0). When it is on, the blend ratio is drawn from Beta(1, 1), uniform on [0, 1], as in MultimediaTechLab/YOLO. See event histograms for non-RGB input profiles.

Validate

val() returns a dictionary of metrics/ keys covering precision, recall, mAP 50 and mAP 50-95, measured against any dataset in the format you trained on.

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt")metrics = model.val(data="my-dataset.yaml") print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"])

libreyolo val model=LibreYOLO9s.pt data=my-dataset.yaml

# The bundled COCO yaml carries an embedded download script, so it# needs explicit permission unless the dataset is already local.libreyolo val model=LibreYOLO9c.pt data=coco.yaml imgsz=640 \  allow_download_scripts=True

Export

A tick holds for all three variants: where they differ, the matrix carries the weakest of the three.

An exported artifact loads back through LibreYOLO() on its file suffix, so a .onnx or .engine file behaves like a checkpoint and returns the same Results. Running the graph in a bare runtime, with no LibreYOLO installed, is also supported, but then preprocessing and postprocessing are yours to write.

For the base detection model, the postprocessing half of that can move into the graph. nms=True on an ONNX export puts suppression inside the model, and the first output becomes a fixed (1, max_det, 6) tensor whose rows are x1, y1, x2, y2, score, class, zero-padded past the detection count. That graph is batch 1 and carries no dynamic axes. The end-to-end and stride-4 models do not accept the flag.

Each format installs a different extra and takes a few arguments of its own. Both are on that format's page.

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt")model.export(format="onnx", imgsz=640)

libreyolo export model=LibreYOLO9s.pt format=onnx imgsz=640

libreyolo export model=LibreYOLO9s.pt format=onnx nms=True \  conf=0.25 iou=0.45 max_det=300

from libreyolo import LibreYOLO, SAMPLE_IMAGE # The factory routes on the file suffix, so an exported artifact loads# like any checkpoint and returns the same Results object.model = LibreYOLO("LibreYOLO9s.onnx")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy)

TFLite INT8 uses int8=True with calibration data.

ONNX inputs and outputs

Checkpoints

Every published weight file for this family.

Licensing

Citation

@inproceedings{wang2024yolov9,
      title={{YOLOv9}: Learning What You Want to Learn Using Programmable Gradient Information},
      author={Wang, Chien-Yao and Yeh, I-Hau and Liao, Hong-Yuan Mark},
      year={2024},
      booktitle={Proceedings of the European Conference on Computer Vision (ECCV)},
}