# lightly-train: one command for DINOv2/v3 pretraining, YOLO fine-tuning and distillation

> LightlyTrain wraps self-supervised pretraining, detection and segmentation fine-tuning, and distillation into a single Python package. The AGPL-3.0 licence is the first thing to check before you build a product on it.

**lightly-ai/lightly-train** — All-in-one training for vision models (YOLO, ViTs, RT-DETR, DINOv3): pretraining, fine-tuning, distillation.

- Repository: https://github.com/lightly-ai/lightly-train
- Website: https://docs.lightly.ai/train
- Stars: 1,693 · Forks: 119
- Language: Python
- License: AGPL-3.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/lightly-ai-lightly-train

## What lightly-train is for, and who ends up using it

The package covers the part of a vision project that sits before deployment. According to the README, it handles pretraining DINOv2 and DINOv3 foundation models on unlabeled data, then fine-tuning transformer and YOLO-style models for detection and segmentation. Distillation from a teacher model is the third leg. The pyproject.toml description is narrower than the README: "Train models with self-supervised learning in a single command".

That single-command framing is the actual selling point. The people who benefit are teams with a folder of images and no labels, or teams with a small labeled set who want a stronger starting checkpoint than ImageNet weights. The repository topics list depth-estimation, semantic-segmentation, object-detection, embeddings and distillation, so the intended scope is broad within vision and narrow outside it. If your problem is tabular, text or audio, nothing here applies.

The README also points at a second project, LightlyStudio, for visualizing annotations and predictions. That is a separate repository, not a module inside lightly-train.

## The training loop you do not write: Lightning, torchmetrics and SuperGradients underneath

The dependency list in pyproject.toml tells you what is actually running. pytorch_lightning handles the training loop, torch>=2.1.0 and torchvision>=0.16.0 supply the tensor operations, torchmetrics[detection] provides detection metrics, and transformers>=4.46 is pulled in for fine-tuning. lightly>=1.5.26 is the sibling library for self-supervised methods.

Two constraints fall out of that list. The first is SuperGradients: the comments in pyproject.toml say albumentations 1.3 is needed for SuperGradients and that 1.4 has "a lot of errors", which is why the version pin is written as `albumentations>=1.3.1,!=1.4.*` on Python 3.9 and above. The second is Python itself: requires-python is `>=3.8, <3.14`, with the inline note that Python 3.14 is not yet supported by Lightning. A team standardised on 3.14 has to downgrade or wait.

The README's COCO table shows the model family the fine-tuning path produces. ltdetrv2-s-coco is listed at 50.7 mAP 50:95 with 9.9M parameters at 640x640, and the largest entry, dinov3/convnext-large-ltdetr-coco, at 60.0 mAP with 230.0M parameters. Latency in that table is measured with TensorRT on an NVIDIA T4 at batch size 1, with tensorrt==10.13.3.9. Those numbers are the project's own published results, not an independent evaluation.

## Installing lightly-train and running a first pretraining job

The README gives one install line and states support for Python 3.8+, on Windows, Linux or MacOS:

```bash
pip install lightly-train
```

After that, the package is importable as `lightly_train`. The README does not spell out the first training command in the text shown here, so the entry point to check is the documentation at docs.lightly.ai/train, which the README links for installation, Docker and per-task guides. There is also a docker/ directory in the repository and a Docker badge in the README header, so a container path exists alongside pip.

The repository layout is a useful map before you start. Training code lives under src/, runnable examples under examples/ (with cpp/, deployment/ and notebooks/ subdirectories), and benchmarks under inference_benchmarks/. The Makefile shows the expected working artifacts: a `clean-out` target removes `outputs/`, `lightly_outputs/`, `lightning_logs/`, `lightly_epoch_*.ckpt` and `last.ckpt`. Those directory names are what a completed run leaves behind, so if a job finishes and none of them appear, the run did not reach the checkpointing stage.

For a first real job, the practical sequence is: point the tool at a directory of unlabeled images for pretraining, then take the resulting checkpoint into a fine-tuning run on your labeled detection or segmentation set. The README's workflow section is organised by task (object detection, semantic segmentation, instance segmentation), and the news entries show which backbones each task accepts, DINOv2, DINOv3, or EdgeCrafter ECViT. Start with the smallest backbone your accuracy target allows; the COCO table makes the parameter cost of each step visible.

## Where lightly-train stops being the right tool

The licence is the sharpest limitation. The package is AGPL-3.0, and the README is explicit rather than subtle about it: "Using LightlyTrain at work, in production, on the edge, or to build proprietary models? You likely need a Commercial License." For a team shipping a closed-source product, that sentence turns an evaluation into a procurement conversation. AGPL-3.0 also carries network-use obligations that a permissive licence does not, which matters if you expose the trained model through a service. This is a description of what the README says, not legal advice; the licences/ directory and the NOTICE file in the repository are where the actual terms live.

The second boundary is task coverage. Everything here is vision. The topics and news entries cover detection, instance segmentation, semantic segmentation, depth estimation and embeddings. There is no indication of support for text, tabular or audio work.

The third is the dependency surface. A training stack built on PyTorch Lightning, torchmetrics, transformers, SuperGradients and lightly carries the version-pinning problems that come with it, and the albumentations exclusion in pyproject.toml is a live example of one. If your environment already pins conflicting versions of these libraries, installing lightly-train means resolving that conflict first.

Finally, the README does not document rollback or how to resume from a partially completed run, so plan your checkpoint retention before a long job starts.

## How lightly-train differs from timm and from training DINOv2 yourself

The closest comparison is timm. timm is a model zoo and training-script collection: you pick an architecture, bring your own training script or use its reference recipes, and you own the loop. lightly-train takes the opposite position. It bundles the loop, the augmentation pipeline, the metrics and the checkpointing behind a task-level interface, and the trade-off is that you get less control over the internals. If you need a custom loss or a non-standard data pipeline, timm is the more comfortable place to work; if you want a DINOv2/v3 or LTDETR checkpoint without assembling the recipe, lightly-train is aimed at you.

The second comparison is the do-it-yourself route: cloning the DINOv2 or DINOv3 reference implementation and adapting it. That gives you the research code as published, with the maintenance burden that implies. lightly-train's distillation path, described in the 0.15.0 changelog entry as performing "equally well across dense and global tasks and across all models, from ViTs to hybrids to CNNs", is a packaged method rather than a paper reproduction. The difference is packaging and support, not a claim that the underlying method is unique.

On export, the news entries state that ONNX and TensorRT export is available out of the box for LTDETRv2, including FP16 from 0.14.0. That is a concrete capability the raw research repositories do not ship by default.

## Version cadence, upgrade cost and the AGPL-3.0 question

The release history is dense. v0.17.0 landed on 2026-07-28, v0.16.4 on 2026-07-24 and v0.16.3 on 2026-07-22, and the last push to main was on 2026-08-31. That is active work, and it also means minor versions arrive quickly. The 0.16 line alone introduced LTDETRv2 for object detection and then added LTDETRv2 instance segmentation in 0.17.0. A team that pins to 0.16.x will miss the instance segmentation model; a team that tracks main will re-test often.

The upgrade cost is concentrated in the dependency floor. Because the package pins torch, torchvision, transformers, pytorch_lightning and torchmetrics with lower bounds, moving to a new lightly-train release can force a coordinated bump across your environment. The repository's own tooling is a hint about how much churn the maintainers expect: the Makefile runs ruff, mdformat, pre-commit and a pytest check that formats code inside documentation files, all through `uv run --frozen`.

On licensing, the README's commercial-license sentence is the operative one for production users, and the repository carries a LICENSE file, a NOTICE file and a licences/ directory. Read those before you ship, and treat the AGPL-3.0 label as a design constraint on your architecture rather than a formality.

## Conclusion

Adopt lightly-train if you have unlabeled images and want a DINOv2/v3 or LTDETR checkpoint without writing the training loop, and if AGPL-3.0 fits your distribution model. Skip it if you need a permissive licence for a closed product, or if your task is outside detection, segmentation and classification. Before committing, confirm the Python version your environment runs, since 3.14 is excluded, and read the licensing page for the commercial terms.

## FAQ

### What is lightly-train?

It is a Python package from Lightly AI for pretraining DINOv2 and DINOv3 vision models on unlabeled data, fine-tuning detection and segmentation models, and distilling from a teacher. The README describes it as covering the model development lifecycle from pretraining to edge deployment.

### Is fine-tuning the same as training in lightly-train?

They are separate stages in the same package. Pretraining runs self-supervised learning on unlabeled images, while fine-tuning takes a checkpoint and trains it on a labeled task such as object detection or semantic segmentation. The README lists both as distinct workflows.

### Which Python versions does lightly-train support?

The pyproject.toml sets requires-python to >=3.8, <3.14, with a comment that Python 3.14 is not yet supported by Lightning. The README badge lists 3.8 through 3.13.

### Does lightly-train support YOLO models?

The README describes fine-tuning transformer and YOLO models on detection and segmentation tasks, and the repository topics include yolo. The published COCO result tables in the README cover the LTDETR and LTDETRv2 families rather than YOLO checkpoints.

### What licence does lightly-train use, and do I need a commercial one?

The package is AGPL-3.0, as stated in pyproject.toml and the LICENSE file. The README says that using LightlyTrain at work, in production, on the edge, or to build proprietary models likely requires a Commercial License, with a contact link for requests.

### Can lightly-train export models to ONNX or TensorRT?

The changelog entries state that ONNX and TensorRT export is available out of the box for LTDETRv2, and that FP16 precision export was added in 0.14.0 for all tasks. The README's COCO latency figures are measured with TensorRT on an NVIDIA T4.

## Sources

- [License: AGPL-3.0](https://github.com/lightly-ai/lightly-train/blob/main/LICENSE)
- [lightly-ai/lightly-train on GitHub](https://github.com/lightly-ai/lightly-train)
- [Project website](https://docs.lightly.ai/train)
- [README](https://github.com/lightly-ai/lightly-train/blob/main/README.md)
- [Releases](https://github.com/lightly-ai/lightly-train/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/lightly-ai-lightly-train