> This is the documentation for LibreYOLO 1.5.0. Current version: https://www.libreyolo.com/docs/models/yolo-nas

# YOLO-NAS
A convolutional detector whose backbone and neck came out of Deci.AI's architecture search, built from quantization-aware RepVGG blocks. Its weights are Deci.AI's, licensed for non-commercial use only, and LibreYOLO publishes none of them.
Tasks: Detection, Pose. Install: pip install libreyolo.
Verified against LibreYOLO v1.5.0.

## Install

YOLO-NAS needs no extra beyond the base package.

```bash
pip install libreyolo
```

## Predict

A checkpoint name that is not already on disk is fetched from Deci's public
CDN, not from the LibreYOLO org, which hosts none of these weights. Before the
transfer starts the library prints Deci's license terms once per process, and
before the downloaded file is opened its SHA-256 is checked against a pinned
value. What those terms allow is in [licensing](#licensing).

**Python**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

# A name not already on disk is fetched from Deci's CDN. The download
# prints Deci's license terms first; taking the file accepts them.
model = LibreYOLO("LibreYOLONASs.pt")
result = model(SAMPLE_IMAGE, save=True)

for box in result.boxes:
    print(box.cls, box.conf, box.xyxy)
```

**CLI**

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

**Pose**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

# The -pose suffix picks the pose head and its own set of weights.
model = LibreYOLO("LibreYOLONASs-pose.pt")
result = model(SAMPLE_IMAGE)

print(result.keypoints.xy)
```

The returned `Results` object is the one every family returns, so swapping in a
different detector is a one line change. `conf` sets the confidence threshold
and `iou` the NMS threshold. See [prediction](/docs/v1.5.0/predict) for sources,
streaming and result handling.

## Variants

Detection and pose are the same architecture under different heads, and they
take the same arguments. The sizes in the table below are the detection ones;
pose is published at those and at one smaller size. The pose head predicts the
COCO keypoint set.

| Checkpoint | Input (px) | mAP 50-95 | Params (M) |
| --- | --- | --- | --- |
| `LibreYOLONASl` | 640 | 56.3 | 66.98 |
| `LibreYOLONASm` | 640 | 55.4 | 51.18 |
| `LibreYOLONASs` | 640 | 51.8 | 19.05 |

COCO val2017, 500 images. Published on https://www.visionanalysis.org/

Interactive chart: https://www.visionanalysis.org/embed/scatter?highlight=yolonas-l%2Cyolonas-m%2Cyolonas-s&title=YOLO-NAS%20on%20COCO&subtitle=Accuracy%20against%20latency%2C%20every%20benchmarked%20model

## Train

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreYOLONASs.pt")
model.train(data="my-dataset.yaml", epochs=100, imgsz=640, batch=16)
```

**CLI**

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

**From scratch**

```python
from libreyolo import LibreYOLONAS

# No Deci checkpoint is touched: the model starts from random weights,
# so what comes out of the run derives only from your data.
model = LibreYOLONAS(None, size="s")
model.train(data="my-dataset.yaml", imgsz=640, batch=16)
```

`epochs`, `lr0` and `amp` are resolved per task when you leave them out, so a
pose run starts from different defaults than a detection run. The optimizer
defaults to AdamW. The class count comes from the dataset YAML and the head is
rebuilt for it before the first epoch; on the pose head the keypoint count is
handled the same way, so a COCO pose checkpoint can be fine-tuned onto a
skeleton of a different size.

Fine-tuning starts from Deci's weights, which is what Deci's license covers.
Training from a randomly initialized model involves no Deci checkpoint at all,
and that is the third snippet above.

See [training](/docs/v1.5.0/train) 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.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreYOLONASs.pt")
metrics = model.val(data="my-dataset.yaml")

print(metrics["metrics/mAP50-95"])
print(metrics["metrics/mAP50"])
```

**CLI**

```bash
libreyolo val model=LibreYOLONASs.pt data=my-dataset.yaml
```

**Against COCO**

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

## Export

| Task | ONNX | TorchScript | ExecuTorch | TensorRT | OpenVINO | Paddle | MNN | RKNN | ncnn | TFLite | CoreML | Core AI |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Detection | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |  | yes |
| Pose | yes | yes | yes | yes | yes | yes |  |  | yes |  |  |  |

A "yes" means the export is supported. An empty cell means the exporter refuses that combination.

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.
Each format installs a different extra and takes a few arguments of its own.
Both are on that format's page.

An export is another copy of the same weights in a different container.
Exporting a Deci checkpoint changes neither where the weights came from nor the
license that covers them.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreYOLONASs.pt")
model.export(format="onnx", imgsz=640)
```

**CLI**

```bash
libreyolo export model=LibreYOLONASs.pt format=onnx imgsz=640
```

**Use the exported file**

```python
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("LibreYOLONASs.onnx")
result = model(SAMPLE_IMAGE)

print(result.boxes.xyxy)
```

## Checkpoints

There are none to list. Deci's license forbids redistribution, so the LibreYOLO
org publishes no YOLO-NAS weights and the download resolves elsewhere: a name
of the form `LibreYOLONAS<size>.pt`, or `LibreYOLONAS<size>-pose.pt` for pose,
maps to the matching object on Deci's public CDN.

Only the checkpoints whose SHA-256 the library pins can be fetched that way.
Anything else fails closed rather than opening an unverified third-party
pickle, and has to be downloaded by hand and passed as a path. A file already
on disk loads from its path, with no download and no checksum gate. That
includes a Deci `.pth` under its original name, which the loader recognizes.

## Licensing

Check the license on the Hugging Face repository of the specific weights you download. That repository is authoritative and licenses are not always uniform across a family. This is a description of the licenses involved, not legal advice.

- Original work: YOLO-NAS, Deci.AI
- Upstream license: Deci.AI proprietary, non-commercial
- Upstream source: https://github.com/Deci-AI/super-gradients
- LibreYOLO code: Apache-2.0
- Weights: Deci.AI proprietary, non-commercial, distributed by their authors. LibreYOLO does not host or mirror them.
- Interpretation: Two licenses apply here and they are not the same. The SuperGradients source this port follows is Apache-2.0 and LibreYOLO's own implementation is MIT, so nothing restricts the architecture or the training code. Deci's published checkpoints are a different matter: the YOLO-NAS license grants a revocable, non-transferable right to use them and nothing more. It forbids redistribution and sublicensing, forbids offering them as a managed or remote service, restricts modification and reverse engineering, and rules out commercial use, including any model running in a production environment, unless you hold a separate agreement with Deci. LibreYOLO therefore does not mirror them, and prints those terms once before the download starts. Weights trained from a randomly initialized model on your own data derive from no Deci checkpoint.

LibreYOLO neither hosts nor mirrors these weights: nothing for this family
exists in the LibreYOLO Hugging Face org. Every auto-download goes to Deci's
public CDN instead, prints Deci's terms once per process before it starts, and
is checked against a pinned SHA-256 before the file is opened.

Training from a randomly initialized model is the alternative. The architecture
is Apache-2.0 upstream and MIT here, so a model trained that way on your own
data derives from no Deci checkpoint.

## Citation

YOLO-NAS was released without a paper. The entry below is the one its authors
ask for, covering SuperGradients, the library it shipped in.

```bibtex
@misc{supergradients,
  doi = {10.5281/ZENODO.7789328},
  url = {https://zenodo.org/record/7789328},
  author = {Aharon,  Shay and {Louis-Dupont} and {Ofri Masad} and Yurkova,  Kate and {Lotem Fridman} and {Lkdci} and Khvedchenya,  Eugene and Rubin,  Ran and Bagrov,  Natan and Tymchenko,  Borys and Keren,  Tomer and Zhilko,  Alexander and {Eran-Deci}},
  title = {Super-Gradients},
  publisher = {GitHub},
  journal = {GitHub repository},
  year = {2021},
}
```

Copied from https://github.com/Deci-AI/super-gradients#citing