# lightly-ai/lightly architecture

> Architecture diagram of the GitHub repository lightly-ai/lightly, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lightly-ai/lightly
- Repository: https://github.com/lightly-ai/lightly

## Overview

LightlySSL is a PyTorch-oriented framework for self-supervised computer-vision training and image embeddings. A user can start training through the Python API or CLI: configuration reaches the training entry point, which assembles data, transforms, model and loss, then trains an embedding module. Embedding inference produces vectors, labels and filenames; benchmarking utilities support downstream evaluation. The repository also provides video datasets, cropping tools, and modular model, loss and transform building blocks. Several feature links are documented or implied by the tree rather than shown in sampled call sites, so uncertain links are omitted or marked dashed.

Main entry points: [`lightly/cli/train_cli.py`](https://github.com/lightly-ai/lightly/blob/master/lightly/cli/train_cli.py) (Training CLI), [`lightly/cli/embed_cli.py`](https://github.com/lightly-ai/lightly/blob/master/lightly/cli/embed_cli.py) (Embedding CLI), [`lightly/embedding/embedding.py`](https://github.com/lightly-ai/lightly/blob/master/lightly/embedding/embedding.py) (Embedding trainer), [`lightly/data/dataset.py`](https://github.com/lightly-ai/lightly/blob/master/lightly/data/dataset.py) (Image dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_python_api["Python API<br/>[core.py]"]
  node_training_cli["Training CLI<br/>[train_cli.py]"]
  node_embed_cli["Embedding CLI<br/>[embed_cli.py]"]
end

subgraph group_data["Data and transforms"]
  node_dataset["Image dataset<br/>[dataset.py]"]
  node_video_dataset["Video dataset<br/>[_video.py]"]
  node_transforms["View transforms"]
end

subgraph group_learning["Self-supervised learning"]
  node_model_heads["Model heads<br/>[heads.py]"]
  node_backbones["Backbones<br/>[resnet.py]"]
  node_batch_norm["Batch normalization<br/>[batchnorm.py]"]
  node_losses["SSL losses"]
end

subgraph group_results["Embedding and evaluation"]
  node_embedding["Embedding trainer<br/>[embedding.py]"]
  node_benchmarking["Benchmarking<br/>[knn_classifier.py]"]
end

subgraph group_utilities["Data utilities"]
  node_crop_cli["Crop command<br/>[crop_cli.py]"]
  node_crop_ops["Bounding-box cropping"]
  node_box_utils["Bounding boxes<br/>[bounding_box.py]"]
end

node_user(("User"))

node_user -->|"calls"| node_python_api
node_user -->|"runs"| node_training_cli
node_user -.->|"runs"| node_embed_cli
node_python_api -->|"invokes training"| node_training_cli
node_python_api -->|"invokes embedding"| node_embed_cli
node_training_cli -->|"configures data"| node_dataset
node_training_cli -->|"uses"| node_transforms
node_training_cli -.->|"configures model"| node_model_heads
node_training_cli -->|"configures model"| node_backbones
node_training_cli -->|"selects normalization"| node_batch_norm
node_training_cli -->|"configures criterion"| node_losses
node_training_cli -.->|"trains through"| node_embedding
node_dataset -->|"loads video"| node_video_dataset
node_embed_cli -->|"loads data"| node_dataset
node_embed_cli -->|"applies"| node_transforms
node_embed_cli -.->|"computes embeddings"| node_embedding
node_embedding -->|"reads samples"| node_dataset
node_embedding -->|"uses utilities"| node_benchmarking
node_user -.->|"runs"| node_crop_cli
node_crop_cli -->|"calls"| node_crop_ops
node_crop_ops -->|"uses"| node_box_utils

click node_python_api "https://github.com/lightly-ai/lightly/blob/master/lightly/core.py"
click node_training_cli "https://github.com/lightly-ai/lightly/blob/master/lightly/cli/train_cli.py"
click node_embed_cli "https://github.com/lightly-ai/lightly/blob/master/lightly/cli/embed_cli.py"
click node_dataset "https://github.com/lightly-ai/lightly/blob/master/lightly/data/dataset.py"
click node_video_dataset "https://github.com/lightly-ai/lightly/blob/master/lightly/data/_video.py"
click node_transforms "https://github.com/lightly-ai/lightly/tree/master/lightly/transforms"
click node_model_heads "https://github.com/lightly-ai/lightly/blob/master/lightly/models/modules/heads.py"
click node_backbones "https://github.com/lightly-ai/lightly/blob/master/lightly/models/resnet.py"
click node_batch_norm "https://github.com/lightly-ai/lightly/blob/master/lightly/models/batchnorm.py"
click node_losses "https://github.com/lightly-ai/lightly/tree/master/lightly/loss"
click node_embedding "https://github.com/lightly-ai/lightly/blob/master/lightly/embedding/embedding.py"
click node_benchmarking "https://github.com/lightly-ai/lightly/blob/master/lightly/utils/benchmarking/knn_classifier.py"
click node_crop_cli "https://github.com/lightly-ai/lightly/blob/master/lightly/cli/crop_cli.py"
click node_crop_ops "https://github.com/lightly-ai/lightly/blob/master/lightly/utils/cropping/crop_image_by_bounding_boxes.py"
click node_box_utils "https://github.com/lightly-ai/lightly/blob/master/lightly/utils/bounding_box.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_python_api,node_training_cli,node_embed_cli,node_user toneBlue
class node_dataset,node_video_dataset,node_transforms toneAmber
class node_model_heads,node_backbones,node_batch_norm,node_losses toneMint
class node_embedding,node_benchmarking toneRose
class node_crop_cli,node_crop_ops,node_box_utils toneIndigo
```

## Components

### User entry points

- [Python API](https://github.com/lightly-ai/lightly/blob/master/lightly/core.py): `lightly/core.py`
- [Training CLI](https://github.com/lightly-ai/lightly/blob/master/lightly/cli/train_cli.py): `lightly/cli/train_cli.py`
- [Embedding CLI](https://github.com/lightly-ai/lightly/blob/master/lightly/cli/embed_cli.py): `lightly/cli/embed_cli.py`

### Data and transforms

- [Image dataset](https://github.com/lightly-ai/lightly/blob/master/lightly/data/dataset.py): `lightly/data/dataset.py`
- [Video dataset](https://github.com/lightly-ai/lightly/blob/master/lightly/data/_video.py): `lightly/data/_video.py`
- [View transforms](https://github.com/lightly-ai/lightly/tree/master/lightly/transforms): `lightly/transforms`

### Self-supervised learning

- [Model heads](https://github.com/lightly-ai/lightly/blob/master/lightly/models/modules/heads.py): `lightly/models/modules/heads.py`
- [Backbones](https://github.com/lightly-ai/lightly/blob/master/lightly/models/resnet.py): `lightly/models/resnet.py`
- [Batch normalization](https://github.com/lightly-ai/lightly/blob/master/lightly/models/batchnorm.py): `lightly/models/batchnorm.py`
- [SSL losses](https://github.com/lightly-ai/lightly/tree/master/lightly/loss): `lightly/loss`

### Embedding and evaluation

- [Embedding trainer](https://github.com/lightly-ai/lightly/blob/master/lightly/embedding/embedding.py): `lightly/embedding/embedding.py`
- [Benchmarking](https://github.com/lightly-ai/lightly/blob/master/lightly/utils/benchmarking/knn_classifier.py): `lightly/utils/benchmarking/knn_classifier.py`

### Data utilities

- [Crop command](https://github.com/lightly-ai/lightly/blob/master/lightly/cli/crop_cli.py): `lightly/cli/crop_cli.py`
- [Bounding-box cropping](https://github.com/lightly-ai/lightly/blob/master/lightly/utils/cropping/crop_image_by_bounding_boxes.py): `lightly/utils/cropping/crop_image_by_bounding_boxes.py`
- [Bounding boxes](https://github.com/lightly-ai/lightly/blob/master/lightly/utils/bounding_box.py): `lightly/utils/bounding_box.py`

### Other components

- **User**

## Connections

- User → Python API: calls
- User → Training CLI: runs
- User → Embedding CLI: runs
- Python API → Training CLI: invokes training (evidence: `lightly/core.py`)
- Python API → Embedding CLI: invokes embedding (evidence: `lightly/core.py`)
- Training CLI → Image dataset: configures data (evidence: `lightly/cli/train_cli.py`)
- Training CLI → View transforms: uses (evidence: `lightly/cli/train_cli.py`)
- Training CLI → Model heads: configures model
- Training CLI → Backbones: configures model (evidence: `lightly/cli/train_cli.py`)
- Training CLI → Batch normalization: selects normalization (evidence: `lightly/cli/train_cli.py`)
- Training CLI → SSL losses: configures criterion (evidence: `lightly/cli/train_cli.py`)
- Training CLI → Embedding trainer: trains through
- Image dataset → Video dataset: loads video (evidence: `lightly/data/dataset.py`)
- Embedding CLI → Image dataset: loads data (evidence: `lightly/cli/embed_cli.py`)
- Embedding CLI → View transforms: applies (evidence: `lightly/cli/embed_cli.py`)
- Embedding CLI → Embedding trainer: computes embeddings
- Embedding trainer → Image dataset: reads samples (evidence: `lightly/embedding/embedding.py`)
- Embedding trainer → Benchmarking: uses utilities (evidence: `lightly/embedding/embedding.py`)
- User → Crop command: runs
- Crop command → Bounding-box cropping: calls (evidence: `lightly/cli/crop_cli.py`)
- Bounding-box cropping → Bounding boxes: uses (evidence: `lightly/utils/cropping/crop_image_by_bounding_boxes.py`)
