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

# YOLOX
YOLOX is an anchor-free, single-stage detector with a decoupled classification-regression head, trained with SimOTA label assignment. LibreYOLO supports it for detection.
Tasks: Detection. Install: pip install libreyolo.
Verified against LibreYOLO v1.5.0.

## Install

YOLOX needs no extra beyond the base package.

```bash
pip install libreyolo
```

## Predict

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

**Python**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibreYOLOXs.pt")
result = model(SAMPLE_IMAGE, save=True)

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

**CLI**

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

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 applied across the three decoupled prediction
scales. See [prediction](/docs/v1.5.0/predict) for sources, streaming and result
handling.

## Variants

Six sizes share the same CSP backbone and PAFPN neck. The two smallest, `n`
and `t`, run at a smaller fixed input resolution than the other four; the
benchmark table below carries the exact figure for each.

| Checkpoint | Input (px) | mAP 50-95 | Params (M) |
| --- | --- | --- | --- |
| `LibreYOLOXnano` | 416 | 28.8 | 0.91 |
| `LibreYOLOXtiny` | 416 | 35.1 | 5.06 |
| `LibreYOLOXl` | 640 | 53.9 | 54.21 |
| `LibreYOLOXm` | 640 | 50.9 | 25.33 |
| `LibreYOLOXs` | 640 | 43.0 | 8.97 |
| `LibreYOLOXx` | 640 | 56.3 | 99.07 |

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

Interactive chart: https://www.visionanalysis.org/embed/scatter?highlight=yolox-nano%2Cyolox-tiny%2Cyolox-l%2Cyolox-m%2Cyolox-s%2Cyolox-x&title=YOLOX%20on%20COCO&subtitle=Accuracy%20against%20latency%2C%20every%20benchmarked%20model

## Train

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreYOLOXs.pt")
model.train(data="my-dataset.yaml", epochs=300, imgsz=640, batch=16, lr0=0.01)
```

**CLI**

```bash
libreyolo train model=LibreYOLOXs.pt data=my-dataset.yaml \
  epochs=300 imgsz=640 batch=16 lr0=0.01
```

Left alone, the trainer runs 300 epochs at `lr0=0.01` with SGD momentum 0.9, a
5-epoch warmup and mosaic and mixup augmentation switched off for the final 15
epochs. `train()` also accepts a `pretrained` argument, but the value is never
read inside the method: training always continues from whatever weights the
model was constructed with, so `pretrained=False` does not reinitialize the
network.

`imgsz` defaults to a fixed value in the base training config, not to the
loaded checkpoint's native resolution. That affects the `n` and `t`
checkpoints specifically: continuing to train either one without setting
`imgsz` explicitly switches it up to the larger default rather than the
smaller size it was published at.

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("LibreYOLOXs.pt")
metrics = model.val(data="my-dataset.yaml")

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

**CLI**

```bash
libreyolo val model=LibreYOLOXs.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=LibreYOLOXn.pt data=coco.yaml imgsz=416 \
  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 |

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.
A CoreML export can bake NMS into the graph with `nms=True`; YOLOX and YOLOv9
are the only two families that flag currently accepts.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreYOLOXs.pt")
model.export(format="onnx", imgsz=640)
model.export(format="tensorrt", imgsz=640, half=True)
```

**CLI**

```bash
libreyolo export model=LibreYOLOXs.pt format=onnx imgsz=640
libreyolo export model=LibreYOLOXs.pt format=tensorrt imgsz=640 half=True
```

**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("LibreYOLOXs.onnx")
result = model(SAMPLE_IMAGE)

print(result.boxes.xyxy)
```

## Checkpoints

Every published weight file for this family.

| File | Input (px) | Task | Weights license |
| --- | --- | --- | --- |
| `LibreYOLOXn.pt` | 416 | Detection | apache-2.0 |
| `LibreYOLOXt.pt` | 416 | Detection | apache-2.0 |
| `LibreYOLOXs.pt` | 640 | Detection | apache-2.0 |
| `LibreYOLOXm.pt` | 640 | Detection | apache-2.0 |
| `LibreYOLOXl.pt` | 640 | Detection | apache-2.0 |
| `LibreYOLOXx.pt` | 640 | Detection | apache-2.0 |

## 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: YOLOX, Megvii
- Upstream license: Apache-2.0
- Upstream source: https://github.com/Megvii-BaseDetection/YOLOX
- LibreYOLO code: Apache-2.0
- Weights: Apache-2.0, republished at https://huggingface.co/LibreYOLO
- Interpretation: Apache-2.0 is a permissive license, so these weights can be used in commercial and closed-source products. It asks you to keep its license text and attribution notices with any copy of the weights you redistribute, and it grants a patent license. It places no obligation on your own application code, and weights you train yourself on your own data are yours.

## Citation

```bibtex
@article{yolox2021,
  title={YOLOX: Exceeding YOLO Series in 2021},
  author={Ge, Zheng and Liu, Songtao and Wang, Feng and Li, Zeming and Sun, Jian},
  journal={arXiv preprint arXiv:2107.08430},
  year={2021}
}
```

Copied from https://github.com/Megvii-BaseDetection/YOLOX#cite-yolox


## YOLOX architecture

- YOLOX N: [SVG](/diagrams/models/yolox/n.svg), [interactive diagram](/diagrams/models/yolox/n.html)
- YOLOX T: [SVG](/diagrams/models/yolox/t.svg), [interactive diagram](/diagrams/models/yolox/t.html)
- YOLOX S: [SVG](/diagrams/models/yolox/s.svg), [interactive diagram](/diagrams/models/yolox/s.html)
- YOLOX M: [SVG](/diagrams/models/yolox/m.svg), [interactive diagram](/diagrams/models/yolox/m.html)
- YOLOX L: [SVG](/diagrams/models/yolox/l.svg), [interactive diagram](/diagrams/models/yolox/l.html)
- YOLOX X: [SVG](/diagrams/models/yolox/x.svg), [interactive diagram](/diagrams/models/yolox/x.html)
- YOLOX regular family: [SVG](/diagrams/models/yolox/family-regular.svg), [interactive diagram](/diagrams/models/yolox/family-regular.html)