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

# ConvNeXt
ConvNeXt is an image classifier built entirely from standard convolutions, modernized block by block from a ResNet toward the design choices of a vision transformer. LibreYOLO supports it for one task: classification.
Tasks: classify. Install: pip install libreyolo.
Verified against LibreYOLO v1.5.0.

## Install

ConvNeXt needs no optional extra. Everything it imports is in the base
install.

```bash
pip install libreyolo
```

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

```bash
pip install "libreyolo[lora]"
```

## Predict

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

**Python**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibreConvNeXtt-cls.pt")
result = model(SAMPLE_IMAGE, save=True)

print(result.probs.top1, result.probs.top1conf)
print(result.probs.top5)
```

**CLI**

```bash
libreyolo predict model=LibreConvNeXtt-cls.pt source=cat.jpg save=True
```

The returned `Results` object is the one every family returns, so swapping in
a different model is a one line change. A classifier carries no boxes or
masks: `result.probs` holds the whole-image prediction, with `top1`, `top5`,
`top1conf` and `top5conf`. `conf`, `iou` and `max_det` are accepted for API
parity but have no effect, since there is nothing to threshold or suppress on
a single probability vector. See [prediction](/docs/v1.5.0/predict) for sources,
streaming and result handling.

## Variants

Three sizes, tiny/small/base, all trained and evaluated the same way, so
picking one is a straight parameter-count-for-accuracy trade. The task is
fixed: every size covers classification only. The weights filename ends
`-cls.pt` on every size, and that suffix is what the factory reads to route
to this family; no `task=` argument is needed.

## Train

Fine-tuning starts from the published ImageNet backbone and rebuilds the
final classifier layer to the target dataset's class count automatically.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreConvNeXtt-cls.pt")
model.train(data="imagenette160", epochs=5)
```

**CLI**

```bash
libreyolo train model=LibreConvNeXtt-cls.pt data=imagenette160 epochs=5
```

**LoRA**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreConvNeXtt-cls.pt")
model.train(data="imagenette160", epochs=5, lora=True)
```

**Multi-GPU**

```bash
libreyolo train model=LibreConvNeXtt-cls.pt data=imagenette160 \
  epochs=50 device=0,1 batch=-1
```

Left alone, the trainer runs 100 epochs at `lr0=1e-3` with AdamW, a batch of
64 and early stopping after 50 epochs without improvement. `data` accepts a
dataset root (`train/` and `val/`, one folder per class), a known short name
such as `imagenette160`, or a `.zip` URL. ConvNeXt's blocks carry the
`nn.Linear` MLPs LoRA needs, so `lora=True` is supported here, and injects
adapters into the block MLPs rather than fine-tuning the full backbone.

See [training](/docs/v1.5.0/train) for datasets, augmentation, multi-GPU and
loggers.

## Validate

`val()` returns a dictionary of `metrics/` keys. For classification that is
top-1 and top-5 accuracy over the validation split.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreConvNeXtt-cls.pt")
metrics = model.val(data="imagenette160")

print(metrics["metrics/accuracy_top1"])
print(metrics["metrics/accuracy_top5"])
```

**CLI**

```bash
libreyolo val model=LibreConvNeXtt-cls.pt data=imagenette160
```

## Export

| Task | ONNX | TorchScript | ExecuTorch | TensorRT | OpenVINO | Paddle | MNN | RKNN | ncnn | TFLite | CoreML | Core AI |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| classify | 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`. [Export](/docs/v1.5.0/export) lists the arguments every format accepts
and the extras a few of them add.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreConvNeXtt-cls.pt")
model.export(format="onnx")
model.export(format="tensorrt", half=True)
```

**CLI**

```bash
libreyolo export model=LibreConvNeXtt-cls.pt format=onnx
libreyolo export model=LibreConvNeXtt-cls.pt format=tensorrt 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("LibreConvNeXtt-cls.onnx")
result = model(SAMPLE_IMAGE)

print(result.probs.top1)
```

## Checkpoints

Every published weight file for this family.

| File | Input (px) | Task | Weights license |
| --- | --- | --- | --- |
| `LibreConvNeXtt-cls.pt` | 224 | classify | apache-2.0 |
| `LibreConvNeXts-cls.pt` | 224 | classify | apache-2.0 |
| `LibreConvNeXtb-cls.pt` | 224 | classify | 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: ConvNeXt, Meta AI (FAIR)
- Upstream license: Apache-2.0
- Upstream source: https://github.com/huggingface/pytorch-image-models
- LibreYOLO code: MIT
- 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. The architecture is Meta AI's original design, released under MIT at facebookresearch/ConvNeXt; the block definitions, layer-scale parameter and module naming that LibreYOLO's implementation follows come from timm, whose convnext_{tiny,small,base}.fb_in1k ImageNet-1k weights are licensed Apache-2.0 and are what LibreYOLO ships. Only ConvNeXt V1 is shipped here: ConvNeXt-V2's small pretrained checkpoints are CC-BY-NC 4.0 and are deliberately excluded as not redistributable in a commercial library.

Only ConvNeXt V1 is shipped in this family. ConvNeXt-V2's small pretrained
checkpoints are CC-BY-NC 4.0 and are deliberately excluded, since a
non-commercial weight cannot be redistributed inside an MIT/commercial
library.

## Citation

```bibtex
@Article{liu2022convnet,
  author  = {Zhuang Liu and Hanzi Mao and Chao-Yuan Wu and Christoph Feichtenhofer and Trevor Darrell and Saining Xie},
  title   = {A ConvNet for the 2020s},
  journal = {Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR)},
  year    = {2022},
}
```

Copied from https://github.com/facebookresearch/ConvNeXt#citation


## ConvNeXt architecture

- ConvNeXt t: [SVG](/diagrams/models/convnext/t-classify.svg), [interactive diagram](/diagrams/models/convnext/t-classify.html)
- ConvNeXt s: [SVG](/diagrams/models/convnext/s-classify.svg), [interactive diagram](/diagrams/models/convnext/s-classify.html)
- ConvNeXt b: [SVG](/diagrams/models/convnext/b-classify.svg), [interactive diagram](/diagrams/models/convnext/b-classify.html)
- ConvNeXt family: [SVG](/diagrams/models/convnext/family-classify.svg), [interactive diagram](/diagrams/models/convnext/family-classify.html)