# LightlySSL

> A PyTorch-style library of self-supervised learning building blocks — 20+ methods from MoCo and SimCLR to DINOv2, CAPI and LeJEPA

- Category: Training & Fine-Tuning / Efficient Training
- Language: Python
- Licence: MIT
- Repository: https://github.com/lightly-ai/lightly
- Website: https://docs.lightly.ai/self-supervised-learning/
- Canonical page: https://ai-tldr.dev/tools/lightly-ssl/

## In short

LightlySSL is a computer vision framework for self-supervised learning — pre-training an image model on unlabelled data before any labelled fine-tuning. It sits in the Efficient Training category of the Training & Fine-Tuning tools and is open-source, written in Python and licensed MIT. To get started: install from PyPI.

## Overview

LightlySSL is a computer vision framework for self-supervised learning — pre-training an image model on unlabelled data before any labelled fine-tuning. Rather than a one-command trainer, it is a modular library that exposes the pieces each method is built from: loss functions (`lightly.loss`), projection and prediction heads (`lightly.models.modules.heads`), multi-view transforms (`lightly.transforms`) and a dataset wrapper over an image folder. You assemble them in ordinary PyTorch code around whatever backbone you like, which is what makes swapping SimCLR for SimSiam a change of two objects rather than a rewrite.

Over twenty methods are implemented with reference examples, spanning the whole arc of the field: MoCo, SimCLR, BYOL, SwAV, DenseCL, SimSiam, Barlow Twins, DetConS, DINO, NNCLR, VICReg, DCL/DCLW, MAE, iBOT, SimMIM, MSN, PMSN, DINOv2, FroSSL, AIM, CAPI, LeJEPA and Pixio. Each ships in three forms — plain PyTorch, PyTorch Lightning, and distributed PyTorch Lightning — plus Colab notebooks, so the same method can be tried on one GPU and then scaled out without re-deriving the training loop. The repository also publishes benchmark tables on ImageNet1k, ImageNet100, Imagenette and CIFAR-10.

Requirements are modest and explicit: Python 3.8+ (not yet 3.13, because PyTorch lacks support), PyTorch ≥ 1.11, Torchvision ≥ 0.12 and PyTorch Lightning ≥ 1.7.1, with PyTorch and Lightning 2.0+ supported. The library is open source; Lightly also sells a commercial version with Docker support and single-command pretraining for embedding, classification, detection and segmentation, and runs separate open-source projects around it — LightlyTrain for SSL and distillation pretraining, and LightlyStudio for data curation, visualization and annotation.

## What it does

- Modular by design — losses, model heads and multi-view transforms are exposed as low-level building blocks you compose in PyTorch
- 20+ implemented methods including MoCo, SimCLR, BYOL, SwAV, SimSiam, Barlow Twins, DINO, VICReg, MAE, iBOT, SimMIM, DINOv2, AIM, CAPI, LeJEPA and Pixio
- Every method provided in plain PyTorch, PyTorch Lightning and distributed PyTorch Lightning variants, each with a Colab notebook
- Works with any custom backbone — the examples use a torchvision ResNet with its classification head replaced by Identity
- Distributed training through PyTorch Lightning
- Published benchmarks on ImageNet1k, ImageNet100, Imagenette and CIFAR-10

## Getting started

Python 3.8+ on Linux or macOS is the recommended environment (Python 3.13 is not supported yet). Install into a dedicated virtualenv.

1. Install from PyPI

   Pulls in the dependencies needed for the full feature set: PyTorch ≥ 1.11, Torchvision ≥ 0.12 and PyTorch Lightning ≥ 1.7.1.

```bash
pip3 install lightly
```

2. Build a model from the blocks

   A SimCLR model is a backbone plus a projection head. Dropping the backbone's classification head leaves the features.

```python
import torch, torchvision
from lightly import loss, transforms
from lightly.data import LightlyDataset
from lightly.models.modules import heads

class SimCLR(torch.nn.Module):
    def __init__(self, backbone):
        super().__init__()
        self.backbone = backbone
        self.projection_head = heads.SimCLRProjectionHead(
            input_dim=512, hidden_dim=512, output_dim=128,
        )

    def forward(self, x):
        features = self.backbone(x).flatten(start_dim=1)
        return self.projection_head(features)

backbone = torchvision.models.resnet18()
backbone.fc = torch.nn.Identity()
model = SimCLR(backbone)
```

3. Point a dataset at your image folder

   The transform produces several random views per image — that pairing is what the contrastive loss learns from.

```python
transform = transforms.SimCLRTransform(input_size=32, cj_prob=0.5)
dataset = LightlyDataset(input_dir="./my/dataset/", transform=transform)
dataloader = torch.utils.data.DataLoader(
    dataset, batch_size=128, shuffle=True,
)
```

4. Train in a plain PyTorch loop

   The loss is just another module, so the loop is the one you already write. Swapping in SimSiam means changing the model and the loss, nothing else.

```python
criterion = loss.NTXentLoss(temperature=0.5)
optimizer = torch.optim.SGD(model.parameters(), lr=0.1, weight_decay=1e-6)

for epoch in range(10):
    for (view0, view1), targets, filenames in dataloader:
        z0, z1 = model(view0), model(view1)
        l = criterion(z0, z1)
        l.backward()
        optimizer.step()
        optimizer.zero_grad()
```

## When to use it

- Pre-train a vision backbone on a large pile of unlabelled images before spending a labelling budget
- Reproduce or compare SSL methods on the same data with matched training code rather than each paper's own repo
- Take one piece — an NT-Xent loss or a DINO head — into an existing PyTorch training script
- Scale a method from a single GPU to distributed training by switching to the PyTorch Lightning variant
