RT-DETR

Install

RT-DETR needs no optional extra. Everything it imports is in the base install, and the rtdetr extra is a stable name that adds nothing to it.

pip install libreyolo

Adapter fine-tuning with lora=True is the exception, and needs the lora extra.

pip install "libreyolo[lora]"

Predict

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

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

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

from libreyolo import LibreYOLO # The version is part of the file name, and the factory routes on the# checkpoint, so all three load the same way.model = LibreYOLO("LibreRTDETRv4s.pt") # Any source the library accepts: file, folder, URL, webcam index,# RTSP stream, or a .streams listfor result in model.predict("clip.mp4", stream=True, save=True):    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. conf and max_det filter a top-k decode over queries and classes; there is no NMS step to tune, and iou is accepted but unused. See prediction for sources, streaming and result handling.

Variants

Three versions, one task between them, and the size codes do not run in a single series. Version 1 names its sizes after the backbone, ResNet or HGNetv2. Version 2 reuses the ResNet names only: version 1 already ships the two HGNetv2 sizes, and version 2's results there were close enough that LibreYOLO publishes no duplicate weights for them. Version 4 uses a plain letter series, which collides with version 1's HGNetv2 names, so a size code on its own does not identify a model. The version is written into the checkpoint file name.

Version 2 keeps version 1's architecture and state dict layout and changes how the deformable attention samples, which is why the two are told apart by the metadata in the checkpoint rather than by shape. Version 4 is a different lineage: it reuses D-FINE's architecture and trainer, and its weights come from distilling a DINOv3 vision foundation model teacher into an HGNetv2 student. In LibreYOLO LibreRTDETRv4 is a subclass of LibreDFINE with the mask head pinned off, so it stays detection only.

Train

Training starts from a published checkpoint. pretrained is accepted and then dropped on all three versions, so pretrained=False does not give you a randomly initialized model.

from libreyolo import LibreYOLO model = LibreYOLO("LibreRTDETRr18.pt") # coco128.yaml downloads a 128-image sample on first use. Point `data`# at your own dataset YAML for a real run.model.train(data="coco128.yaml", epochs=50, batch=4, lr0=1e-4)

libreyolo train model=LibreRTDETRr18.pt data=coco128.yaml \  epochs=50 batch=4 lr0=1e-4

# Needs the lora extra: pip install "libreyolo[lora]"from libreyolo import LibreYOLO model = LibreYOLO("LibreRTDETRr18.pt")model.train(data="coco128.yaml", epochs=50, lora=True)

libreyolo train model=LibreRTDETRr18.pt data=coco128.yaml \  epochs=50 device=0,1

Learning rate is the argument to get right, and each version carries its own default rather than the library-wide one. The Python train() signature reads it from that version's training config, and the CLI resolves the same value when lr0 is not passed. Versions 1 and 2 also take lr_backbone and default it to a twentieth of lr0, following the original recipe; version 4 runs through the D-FINE trainer, which scales the backbone parameter group with backbone_lr_mult instead.

Leave imgsz at the checkpoint's native size unless you have a reason to change it. Validation and prediction at other sizes work, with one residual: a rectangular size whose token count matches the native size still reuses an embedding built for the wrong aspect ratio.

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

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("LibreRTDETRr18.pt") # val() returns a plain dict, not an objectmetrics = model.val(data="coco128.yaml") print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"])print(metrics["metrics/precision"], metrics["metrics/recall"])

libreyolo val model=LibreRTDETRr18.pt data=coco128.yaml

# coco-val-only.yaml fetches the 5000 val2017 images and skips the# training set. It carries an embedded download script, so it needs# explicit permission unless the dataset is already local.libreyolo val model=LibreRTDETRr18.pt data=coco-val-only.yaml \  allow_download_scripts=True

The rows in the benchmark table above come from the LibreYOLO benchmark harness; the note under that table records which dataset produced them and links the run records.

Export

The matrix covers the lineage as one page: where the three versions disagree about a format, the cell shows the weakest of the three, so nothing here is oversold for whichever version you load.

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.

# Needs the onnx extra: pip install "libreyolo[onnx]"from libreyolo import LibreYOLO model = LibreYOLO("LibreRTDETRr18.pt")path = model.export(format="onnx")print(path)

libreyolo export model=LibreRTDETRr18.pt format=onnx

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("LibreRTDETRr18.onnx")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy)

Checkpoints

Every published weight file for this family.

Licensing

Citation

@misc{lv2023detrs,
      title={DETRs Beat YOLOs on Real-time Object Detection},
      author={Yian Zhao and Wenyu Lv and Shangliang Xu and Jinman Wei and Guanzhong Wang and Qingqing Dang and Yi Liu and Jie Chen},
      year={2023},
      eprint={2304.08069},
      archivePrefix={arXiv},
      primaryClass={cs.CV}
}

@misc{lv2024rtdetrv2improvedbaselinebagoffreebies,
      title={RT-DETRv2: Improved Baseline with Bag-of-Freebies for Real-Time Detection Transformer}, 
      author={Wenyu Lv and Yian Zhao and Qinyao Chang and Kui Huang and Guanzhong Wang and Yi Liu},
      year={2024},
      eprint={2407.17140},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2407.17140}, 
}

The block above is what the authors publish for versions 1 and 2. Version 4 is a separate paper by a different group and has its own citation block at github.com/RT-DETRs/RT-DETRv4; cite that one if you used a version 4 checkpoint.