modern-yolonas

A clean, minimal reimplementation of YOLO-NAS — no factories, no registries, no OmegaConf. Just PyTorch.

Luis Condados   Alan Neves

_{YOLO-NAS-L, confidence 0.40. Source photo by Wilfredor, CC0.}

Live demo  ·  Documentation  ·  Changelog  ·  Contributing  ·  Issues

modern-yolonas is YOLO-NAS object detection rewritten so you can read the whole thing: a model variant is a function, a config is a dataclass, and there is no layer of indirection that exists only to be configurable. state_dict keys match super-gradients exactly, so the original pretrained COCO checkpoints load with strict=True.

Detections come back as supervision Detections, so every annotator, tracker, zone and metric in that ecosystem works on them out of the box. Training runs on Lightning, and the model exports to ONNX and OpenVINO — including a self-contained graph for Frigate.

🚀 Updates

• [2026-09-18] v0.5.0 — training moved to PyTorch Lightning; quantization (yolonas quantize for PTQ, yolonas qat for QAT) on torch.ao.quantization FX graph mode; accuracy is now measured by this project rather than quoted; two mAP bugs and a mosaic bug fixed; license changed from MIT to Apache-2.0 for the source.
• [2026-09-18] v0.4.0 — YoloNASDetector returns supervision.Detections, so results slice and plug into the supervision ecosystem directly.
• [2026-02-05] v0.1 — initial release: S/M/L architectures, pretrained weight loading, training, COCO evaluation, and ONNX export.

🏆 Model Zoo

Box AP on COCO val2017, all 5000 images, at 640×640. There is nothing to download by hand — yolo_nas_s(pretrained=True) and YoloNASDetector("yolo_nas_s") fetch and cache Deci's COCO checkpoints on first use (they carry Deci's own non-commercial terms — see License below).

Every column is measured here, not quoted — regenerate the whole table with uv run examples/model_table.py --coco <coco-root> --half.

📦 Installation

uv add modern-yolonas
# or
pip install modern-yolonas

Optional extras: [onnx], [openvino], [fiftyone], [benchmark], [serve], [demo], [tensorboard], [wandb].

⚡ Quick Start

YoloNASDetector picks CUDA when it is available and falls back to CPU, so the examples below run anywhere. Pass device="cuda", "cpu" or a torch.device to choose explicitly.

Detect objects in an image

import cv2
from modern_yolonas import YoloNASDetector

det = YoloNASDetector("yolo_nas_s")

image = cv2.imread("image.jpg")
detections = det(image)  # an sv.Detections

for box, score, name in zip(detections.xyxy, detections.confidence, detections.data["class_name"]):
    x1, y1, x2, y2 = box
    print(f"{name}: {score:.2f} [{x1:.0f}, {y1:.0f}, {x2:.0f}, {y2:.0f}]")

# Save annotated image
cv2.imwrite("output.jpg", det.annotate(image, detections))

Because the result is a supervision container, filtering is slicing:

people = detections[detections.class_id == 0]
confident = detections[detections.confidence > 0.5]
big = detections[detections.box_area > 5000]

and it plugs straight into the rest of the ecosystem:

import supervision as sv

zone = sv.PolygonZone(polygon=my_polygon)
inside = detections[zone.trigger(detections)]

heatmap_annotator = sv.HeatMapAnnotator()
frame = heatmap_annotator.annotate(frame, detections)

Detect objects in a video

_{YOLO-NAS-L at confidence 0.25, ~70 detections per frame. Clip by Basile Morin, CC BY-SA 4.0 — so this clip, unlike the rest of the repository, is CC BY-SA rather than Apache-2.0.}

from modern_yolonas import YoloNASDetector

det = YoloNASDetector("yolo_nas_s")

# Option 1: Write annotated video directly
stats = det.detect_video_to_file("input.mp4", "output.mp4")
print(f"{stats['total_detections']} detections across {stats['total_frames']} frames")

# Option 2: Iterate frames for custom logic
for frame_idx, frame, detections in det.detect_video("input.mp4"):
    print(f"Frame {frame_idx}: {len(detections)} objects")
    # detections.xyxy, .confidence, .class_id are numpy arrays
    # det.annotate(frame, detections) returns the annotated BGR frame

Live webcam detection

import cv2
from modern_yolonas import YoloNASDetector

det = YoloNASDetector("yolo_nas_s")

for frame_idx, frame, detections in det.detect_video(source=0):  # 0 = default camera
    cv2.imshow("YOLO-NAS", det.annotate(frame, detections))
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break
cv2.destroyAllWindows()

Low-level model API

import torch
from modern_yolonas import yolo_nas_s

model = yolo_nas_s(pretrained=True).eval().cuda()
x = torch.randn(1, 3, 640, 640).cuda()
pred_bboxes, pred_scores = model(x)
# pred_bboxes: [1, 8400, 4] — x1y1x2y2 pixel coordinates
# pred_scores: [1, 8400, 80] — class probabilities

🖥️ CLI

Full reference: CLI docs.

# Detect in images
yolonas detect --model yolo_nas_s --source image.jpg --conf 0.25
yolonas detect --model yolo_nas_l --source images/ --output results/

# Detect in video
yolonas detect --model yolo_nas_s --source video.mp4 --output results/
yolonas detect --model yolo_nas_m --source video.mp4 --skip-frames 2 --conf 0.3

# Training
yolonas train --model yolo_nas_s --data /path/to/dataset --format yolo --epochs 100

# Evaluation
yolonas eval --model yolo_nas_s --data /path/to/coco --split val2017

# Export (needs the extras: pip install "modern-yolonas[onnx]" / [openvino])
yolonas export --model yolo_nas_s --format onnx --output model.onnx
yolonas export --model yolo_nas_s --format openvino --output model.xml

# Export for Frigate (embeds preprocessing + NMS in the graph)
yolonas export --model yolo_nas_s --format onnx --target frigate
yolonas export --model yolo_nas_s --format openvino --target frigate --input-size 320

detectors:
  ov:
    type: openvino
    device: GPU

model:
  model_type: yolonas
  width: 320
  height: 320
  input_tensor: nchw
  input_pixel_format: bgr
  path: /config/model_frigate.xml

📚 Tutorials

Step-by-step notebooks in tutorials/:

Examples

Start with the notebook — install, detect, visualize, and inspect the raw model output in one pass:

• notebooks/quickstart.ipynb

Or the standalone scripts in examples/:

• parity_check.py — verify this implementation matches super-gradients (writes docs/benchmarks/parity.md)
• bench_devices.py — latency across CPU / Intel iGPU / NVIDIA dGPU and FP32 / FP16 / INT8 (writes docs/benchmarks/latency_matrix.md)
• detect_image.py — run detection on a single image
• detect_video.py — run detection on a video file
• detect_webcam.py — live webcam detection

🛠️ Development

uv sync --dev
uv run pre-commit install

uv run pytest tests/ -v
uv run ruff check src/ tests/

Contributions are welcome. Please read CONTRIBUTING.md — it lists the API design principles a change is reviewed against — and the Code of Conduct.

📄 License

Apache-2.0 — applies to the source code only. See LICENSE.

Pretrained weights notice: the pretrained COCO weights downloaded by this library (via pretrained=True) are provided by Deci AI and are subject to Deci's YOLO-NAS license, which restricts commercial use and redistribution. The Apache-2.0 license of this repository does not cover them. If you train your own weights from scratch, those are entirely yours.

🙏 Acknowledgments

This project is a clean-room reimplementation of the YOLO-NAS architecture originally developed by Deci AI and published in their super-gradients library (Apache-2.0). The model architecture, module structure and state_dict key naming were derived from the super-gradients source to enable pretrained weight compatibility.

It also builds directly on supervision, PyTorch Lightning and OpenVINO.

Thanks to everyone who has contributed — in particular Alan Neves, whose work on augmentations, metrics, gradient accumulation, the ONNX export path and super-gradients parity shaped much of the training stack.

⭐ Star History

📖 Citation

If you use modern-yolonas in your research or project, please cite it:

@software{condados2026modernyolonas,
  author       = {Condados, Luis and Neves, Alan},
  title        = {modern-yolonas: A Clean Reimplementation of YOLO-NAS},
  year         = {2026},
  url          = {https://github.com/CondadosAI/modern-yolonas},
  license      = {Apache-2.0}
}