DEIM

Install

Neither version needs an optional extra. Everything they import is in the base install.

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("LibreDEIMn.pt")result = model(SAMPLE_IMAGE, save=True) for box in result.boxes:    print(box.cls, box.conf, box.xyxy)

libreyolo predict model=LibreDEIMn.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 both load the same way.model = LibreYOLO("LibreDEIMv2pico.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

Version 1 ships five sizes, all at the same input size. Version 2 keeps those five names and adds three smaller ones, atto, femto and pico, the first two of which are native at a lower input size than the rest. Five size codes therefore exist in both versions and name different models; the version is written into the checkpoint file name.

Version 1 keeps D-FINE's architecture and swaps its classification objective for the matchability-aware loss from the dense one-to-one recipe, so the two families share almost every state dict key and are told apart by the metadata in the checkpoint. Version 2 keeps that training contract and mixes backbones: HGNetv2 below s, and a DINOv3 vision transformer with a spatial tuning adapter at s and above. That backbone is what puts a second license on those four checkpoints, so read licensing before you ship one.

Train

Training starts from a published checkpoint. pretrained never reaches the trainer: version 1 warns that the key is unknown and ignores it, version 2 removes it. Neither gives you a randomly initialized model.

from libreyolo import LibreYOLO model = LibreYOLO("LibreDEIMn.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=8, lr0=1e-4)

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

from libreyolo import LibreYOLO # Left unset, epochs, batch, imgsz and lr0 come from the released# recipe for the size that was loaded.model = LibreYOLO("LibreDEIMv2pico.pt")model.train(data="coco128.yaml", epochs=50)

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

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

Pass lr0 yourself on version 1. Its Python train() signature defaults to 4e-4, the rate from the published COCO recipe, while the family's training config carries 1e-4 as its fine-tune default, and that lower value is what the CLI resolves when the argument is absent. The config records the measurement behind it: at the batch sizes a fine-tune actually uses, on small datasets, the COCO rate measurably degraded transfer.

Version 2 resolves those defaults itself. Leaving epochs, batch, imgsz and lr0 unset makes it read each one from the released recipe for the size that was loaded, so the small sizes train at their own input resolution without being told, and a value you pass overrides the recipe. imgsz is the argument it constrains: it has to be a positive multiple of 32, and version 2 raises before the run starts otherwise.

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("LibreDEIMn.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=LibreDEIMn.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=LibreDEIMn.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 both versions as one page: where they disagree about a format, the cell shows the weaker of the two, 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("LibreDEIMn.pt")path = model.export(format="onnx")print(path)

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

Checkpoints

Every published weight file for this family.

Licensing

Citation

@misc{huang2024deim,
      title={DEIM: DETR with Improved Matching for Fast Convergence},
      author={Shihua, Huang and Zhichao, Lu and Xiaodong, Cun and Yongjun, Yu and Xiao, Zhou and Xi, Shen},
      booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},
      year={2025},
}

DEIMv2 is a separate paper and has its own citation block at github.com/Intellindust-AI-Lab/DEIMv2; cite that one if you used a version 2 checkpoint.