LightlySSL: a modular PyTorch toolkit for self-supervised image pretraining
A python library for self-supervised learning on images.
At a glance
- What is it?
- LightlySSL exposes the building blocks of contrastive and non-contrastive pretraining (losses, heads, augmentations) rather than a single training script. It suits engineers who want to assemble a custom SSL pipeline; it is the wrong layer if you want a pretrained checkpoint in one command.
- Who is it for?
- Adopt LightlySSL if you already run PyTorch training loops and want the SSL losses, projection heads and augmentation stacks as importable components you can wire into your own code, and if supporting MoCo, SimCLR, BYOL, SwaV, DenseCL, SimSiam or the newer LeJEPA path matches your research plan.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap LightlySSL fills between a paper and a training loop
Self-supervised pretraining papers ship as descriptions of a loss, a pair of network branches and an augmentation policy. Reproducing one means writing the same scaffolding each time: two views of every image, a projection head, a memory bank or momentum encoder, a temperature schedule. LightlySSL packages those parts as importable modules. The README describes it as a "modular framework, which exposes low-level building blocks such as loss functions and model heads", written in a PyTorch-like style, with support for custom backbones and distributed training through PyTorch Lightning. The intended user is an engineer who has a dataset of unlabelled images and a PyTorch codebase already, and who wants the SSL objective without adopting someone else's training script wholesale. It is not aimed at someone who wants to type one command and receive a checkpoint.
What the model table actually covers, and the LeJEPA addition
The README lists MoCo (2019), SimCLR (2020), BYOL (2020), SwaV (2020), DenseCL (2020) and SimSiam (2020), each with a paper link, a docs page and two Colab notebooks, one plain PyTorch and one PyTorch Lightning. That pairing matters: the repository treats the two execution styles as first-class, not as an afterthought. The news section adds LeJEPA support as of May 28, 2026, linking to arXiv paper 2511.08544. The spread of methods is the point. MoCo and SimCLR rely on contrasting negatives; BYOL and SimSiam drop negatives and use prediction and stop-gradient tricks; SwaV uses clustering assignments; DenseCL targets dense rather than image-level features. Having all of these behind one set of heads and losses means you can swap the objective without rewriting the data pipeline. The list is also historical: the newest entries in the table date from 2020, with LeJEPA arriving separately, so anyone expecting the very latest published methods to appear automatically should check the docs rather than assume.
How the pieces fit: backbones, heads, losses, augmentations
The architecture implied by the README is a layering, not an end-to-end trainer. A backbone produces features. A model head (projection MLP, momentum encoder, memory bank) consumes them. A loss function compares the resulting representations across augmented views. Augmentations generate those views. The framework exposes each layer so you can substitute your own. The README states that custom backbone models are supported for self-supervised pretraining, which is the practical consequence of that layering: you are not restricted to a fixed ResNet variant. Distributed training is delegated to PyTorch Lightning, so multi-GPU and multi-node runs follow Lightning's conventions rather than a bespoke launcher. The data flow is therefore the standard SSL loop (sample batch, produce two or more views, encode, project, compute loss, backpropagate through the online branch) with LightlySSL supplying the middle stages and leaving the outer loop to you.
Getting it running: install and the entry points to start from
The package installs from PyPI as lightly, so pip install lightly is the starting point. The README does not print a full training snippet, but it does point to concrete entry points: the docs at docs.lightly.ai/self-supervised-learning, the examples/models page described as containing sample code for all supported models, and the notebooks under examples/notebooks/pytorch/ and examples/notebooks/pytorch_lightning/ in the repository. Each model has its own notebook in both directories, for example moco.ipynb, simclr.ipynb, byol.ipynb, swav.ipynb, densecl.ipynb and simsiam.ipynb. Those two directories are the fastest way to see the intended wiring before writing your own loop. The README does not document specific configuration keys or CLI flags for the library itself, so anything beyond the install line should be read from the docs and the notebooks rather than inferred. If you need a command-line trainer, the README directs you to LightlyTrain instead.
Where the open source library stops
The README is unusually explicit about the boundary. A commercial version exists with "more features, including Docker support and pretraining models for embedding, classification, detection, and segmentation tasks with a single command", reachable through sales@lightly.ai. LightlyTrain, a separate repository, is presented as a way to run SSL and distillation pretraining "in just a few lines of code". LightlyStudio is a third project for visualising, annotating and managing data. So the repository you are evaluating is the low-level layer, and the higher-level conveniences live elsewhere. This is a real limitation, not a marketing footnote: if your goal is a fine-tuned detector next week, the path described in this README runs through a sales conversation, and the open MIT package will not close that gap on its own.
Distributed training, licences and the cost of keeping up
Two maintenance facts are visible in the material. First, release cadence: v1.5.24 on 2026-05-28, v1.5.25 on 2026-06-17 and v1.5.26 on 2026-07-27, with the last push to master on 2026-09-08. That is roughly monthly patch releases through mid-2026, which suggests active upkeep but also means pinning a version is wise if you depend on internal APIs. Second, the licence is MIT, which permits commercial use and modification; the README links to LICENSE.txt for the full text and this article is not legal advice. Because the library is a set of building blocks rather than a frozen application, upgrades can move the pieces you import. The release notes are the place to check before bumping a pinned version in a training pipeline, and the PyTorch Lightning dependency means Lightning upgrades are part of your upgrade surface too. The commercial tier is a separate cost, negotiated rather than published.
When a different tool is the better fit
The clearest alternative named in the README is LightlyTrain, from the same organisation. The difference is one of level. LightlySSL gives you losses, heads and augmentations to assemble into your own loop, which is what you want when you are adapting a method, swapping backbones for a domain-specific encoder, or running an ablation. LightlyTrain is described as providing SSL and distillation pretraining in a few lines of code, which is what you want when the objective is a usable checkpoint and not a research artefact. Choosing between them is mostly a question of how much of the training loop you intend to own. A second boundary sits between the MIT package and the commercial version: Docker support and single-command pretraining for embedding, classification, detection and segmentation are listed as commercial features, so teams whose workflow depends on those should evaluate the commercial product rather than the repository described here.
Editorial conclusion
Adopt LightlySSL if you already run PyTorch training loops and want the SSL losses, projection heads and augmentation stacks as importable components you can wire into your own code, and if supporting MoCo, SimCLR, BYOL, SwaV, DenseCL, SimSiam or the newer LeJEPA path matches your research plan. Do not adopt it if what you actually need is a pretrained checkpoint without writing a training loop; the README points that use case at LightlyTrain and the commercial version instead. Before committing, verify three things against the docs: which of the listed models have runnable examples in the style you need, whether the distributed path through PyTorch Lightning matches your cluster, and what the commercial tier covers that the MIT package does not, since the README states that Docker support and single-command pretraining for embedding, classification, detection and segmentation sit behind a sales contact.
Community notes