# facebookresearch/dinov2 architecture

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

- Interactive diagram: https://gitdiagram.com/facebookresearch/dinov2
- Repository: https://github.com/facebookresearch/dinov2

## Overview

#### Purpose and entry points
This is a Python/PyTorch research repository for DINOv2 self-supervised Vision Transformer (ViT) feature learning, pretrained-model consumption, and downstream evaluation. It also adds Cell-DINO, channel-adaptive microscopy models, XRay-DINO, and DINO.txt vision-language inference. Primary entry points are PyTorch Hub (`hubconf.py`), distributed training (`dinov2/run/train/train.py`), and evaluation CLIs (`dinov2/run/eval/knn.py`, `dinov2/run/eval/linear.py`).

#### Model foundation
The reusable backbone is a ViT with patch embeddings, attention blocks, optional register tokens, and intermediate feature extraction. Core implementation resides in `dinov2/models/vision_transformer.py`, composed from `dinov2/layers/block.py` and `dinov2/layers/attention.py`. This model boundary produces global and patch-level features consumed by SSL losses, evaluators, and task-specific heads.

#### Self-supervised training pipeline
`dinov2/train/ssl_meta_arch.py` defines the student/teacher SSL architecture; `dinov2/train/train.py` runs optimization and checkpoint-oriented training. Training combines DINO class-token distillation, iBOT masked-patch prediction, and KoLeo regularization from `dinov2/loss/dino_clstoken_loss.py`, `dinov2/loss/ibot_patch_loss.py`, and `dinov2/loss/koleo_loss.py`. The orchestration CLI resolves YAML/overrides, launches distributed workers, and writes teacher checkpoints for downstream evaluation.

#### Data and augmentation boundary
Dataset specifications are converted into dataset/loader pipelines under `dinov2/data/datasets/` and `dinov2/data/loaders.py`; image transformations, multi-crop augmentation, collation, and masking are isolated in `dinov2/data/augmentations.py`, `dinov2/data/collate.py`, and `dinov2/data/masking.py`. Standard ImageNet and ImageNet-22k coexist with microscopy-specific adapters/datasets such as `dinov2/data/datasets/cell_dino/chammi_hpa.py` and channel-aware transforms in `dinov2/data/cell_dino/transforms.py`.

#### Distributed execution and state
Training targets Linux GPU clusters: PyTorch 2+, CUDA, xFormers, SLURM, and Submitit-style launch flow through `dinov2/run/submit.py`. Distributed process setup is centralized in `dinov2/distributed/__init__.py`; large-model sharding support is in `dinov2/fsdp/__init__.py`. Checkpoint load/save and resume compatibility form the persistence boundary in `dinov2/utils/checkpoint.py`; cluster/config utilities are in `dinov2/utils/cluster.py` and `dinov2/utils/config.py`.

#### Evaluation and downstream tasks
Feature quality evaluation has k-NN, linear probing, and logistic regression implementations in `dinov2/eval/knn.py`, `dinov2/eval/linear.py`, and `dinov2/eval/log_regression.py`, invoked by matching `dinov2/run/eval/` CLIs. Cell-DINO has separate k-NN/linear implementations in `dinov2/eval/cell_dino/knn.py` and `dinov2/eval/cell_dino/linear.py`. Dense-task extensions attach ViT features to depth and segmentation stacks: `dinov2/eval/depth/models/builder.py`, `dinov2/eval/segmentation/models/decode_heads/linear_head.py`, and Mask2Former integration in `dinov2/eval/segmentation_m2f/models/segmentors/encoder_decoder_mask2former.py`; these require mmcv/mmsegmentation extras.

#### Distribution and pretrained interfaces
`hubconf.py` exposes stable `torch.hub.load` constructors backed by standard, Cell-DINO, XRay-DINO, depth, classifier, and DINO.txt factories under `dinov2/hub/`. Key loading paths include `dinov2/hub/backbones.py`, `dinov2/hub/cell_dino/backbones.py`, `dinov2/hub/xray_dino/backbones.py`, and `dinov2/hub/text/dinotxt_model.py`. Checkpoints are external artifacts fetched from Meta/public URLs or supplied locally; model/license boundaries differ between Apache-licensed base DINOv2 and noncommercial research Cell-DINO/XRay-DINO assets.

Main entry points: [`dinov2/models/vision_transformer.py`](https://github.com/facebookresearch/dinov2/blob/main/dinov2/models/vision_transformer.py) (Vision Transformer), [`dinov2/train/train.py`](https://github.com/facebookresearch/dinov2/blob/main/dinov2/train/train.py) (Optimization loop), [`dinov2/train/ssl_meta_arch.py`](https://github.com/facebookresearch/dinov2/blob/main/dinov2/train/ssl_meta_arch.py) (Student-teacher SSL), [`dinov2/utils/checkpoint.py`](https://github.com/facebookresearch/dinov2/blob/main/dinov2/utils/checkpoint.py) (Checkpoint persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["ViT foundation"]
  node_vit["Vision Transformer<br/>feature backbone"]
  node_vit_layers["Attention blocks<br/>ViT layers<br/>[block.py]"]
end

subgraph group_training["SSL training"]
  node_train_cli["Distributed training CLI<br/>training entry point<br/>[train.py]"]
  node_launcher["Cluster launcher<br/>SLURM submission<br/>[submit.py]"]
  node_distributed["Distributed and FSDP<br/>execution runtime<br/>[__init__.py]"]
  node_ssl_arch["Student-teacher SSL<br/>meta architecture<br/>[ssl_meta_arch.py]"]
  node_losses["DINO, iBOT, KoLeo losses<br/>SSL objectives"]
  node_train_engine["Optimization loop<br/>trainer<br/>[train.py]"]
  node_checkpoints[("Checkpoint persistence<br/>training state<br/>[checkpoint.py]")]
end

subgraph group_data["Data pipeline"]
  node_datasets_loaders["Datasets and loaders<br/>input pipeline<br/>[loaders.py]"]
  node_augmentation["Multi-crop augmentation<br/>image transforms<br/>[augmentations.py]"]
  node_cell_data["Microscopy adapters<br/>channel-aware data<br/>[chammi_hpa.py]"]
end

subgraph group_downstream["Evaluation and distribution"]
  node_hub["PyTorch Hub<br/>public constructors<br/>[hubconf.py]"]
  node_hub_factories["Model factories<br/>pretrained loaders"]
  node_artifacts[("External checkpoints<br/>model artifacts")]
  node_eval_clis["Evaluation CLIs<br/>downstream entry points<br/>[knn.py]"]
  node_feature_eval["Feature evaluators<br/>k-NN and probes<br/>[knn.py]"]
  node_dense_tasks["Dense task heads<br/>depth and segmentation<br/>[builder.py]"]
end

node_hub -->|"exports"| node_hub_factories
node_hub_factories -->|"loads weights"| node_artifacts
node_hub_factories -->|"constructs"| node_vit
node_vit_layers -->|"composes"| node_vit
node_augmentation -->|"transforms batches"| node_datasets_loaders
node_cell_data -->|"extends"| node_datasets_loaders
node_datasets_loaders -->|"multi-crop batches"| node_ssl_arch
node_train_cli -->|"submits"| node_launcher
node_train_cli -->|"starts"| node_train_engine
node_launcher -->|"allocates workers"| node_distributed
node_distributed -->|"runs"| node_train_engine
node_ssl_arch -->|"student and teacher"| node_vit
node_ssl_arch -->|"computes objectives"| node_losses
node_losses -->|"gradients"| node_train_engine
node_train_engine -->|"saves/resumes"| node_checkpoints
node_checkpoints -->|"teacher weights"| node_feature_eval
node_eval_clis -->|"invokes"| node_feature_eval
node_feature_eval -->|"extracts features"| node_vit
node_dense_tasks -->|"uses features"| node_vit
node_checkpoints -.->|"local weights"| node_hub_factories

click node_hub "https://github.com/facebookresearch/dinov2/blob/main/hubconf.py"
click node_vit "https://github.com/facebookresearch/dinov2/blob/main/dinov2/models/vision_transformer.py"
click node_vit_layers "https://github.com/facebookresearch/dinov2/blob/main/dinov2/layers/block.py"
click node_datasets_loaders "https://github.com/facebookresearch/dinov2/blob/main/dinov2/data/loaders.py"
click node_augmentation "https://github.com/facebookresearch/dinov2/blob/main/dinov2/data/augmentations.py"
click node_cell_data "https://github.com/facebookresearch/dinov2/blob/main/dinov2/data/datasets/cell_dino/chammi_hpa.py"
click node_train_cli "https://github.com/facebookresearch/dinov2/blob/main/dinov2/run/train/train.py"
click node_launcher "https://github.com/facebookresearch/dinov2/blob/main/dinov2/run/submit.py"
click node_distributed "https://github.com/facebookresearch/dinov2/blob/main/dinov2/distributed/__init__.py"
click node_ssl_arch "https://github.com/facebookresearch/dinov2/blob/main/dinov2/train/ssl_meta_arch.py"
click node_losses "https://github.com/facebookresearch/dinov2/blob/main/dinov2/loss/dino_clstoken_loss.py"
click node_train_engine "https://github.com/facebookresearch/dinov2/blob/main/dinov2/train/train.py"
click node_checkpoints "https://github.com/facebookresearch/dinov2/blob/main/dinov2/utils/checkpoint.py"
click node_eval_clis "https://github.com/facebookresearch/dinov2/blob/main/dinov2/run/eval/knn.py"
click node_feature_eval "https://github.com/facebookresearch/dinov2/blob/main/dinov2/eval/knn.py"
click node_dense_tasks "https://github.com/facebookresearch/dinov2/blob/main/dinov2/eval/depth/models/builder.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_vit,node_vit_layers toneBlue
class node_train_cli,node_launcher,node_distributed,node_ssl_arch,node_losses,node_train_engine,node_checkpoints toneAmber
class node_datasets_loaders,node_augmentation,node_cell_data toneMint
class node_hub,node_hub_factories,node_artifacts,node_eval_clis,node_feature_eval,node_dense_tasks toneRose
```

## Components

### ViT foundation

- [Vision Transformer](https://github.com/facebookresearch/dinov2/blob/main/dinov2/models/vision_transformer.py): feature backbone · Produces global and patch-level features. · `dinov2/models/vision_transformer.py`
- [Attention blocks](https://github.com/facebookresearch/dinov2/blob/main/dinov2/layers/block.py): ViT layers · `dinov2/layers/block.py`

### SSL training

- [Distributed training CLI](https://github.com/facebookresearch/dinov2/blob/main/dinov2/run/train/train.py): training entry point · Resolves configuration and launches training. · `dinov2/run/train/train.py`
- [Cluster launcher](https://github.com/facebookresearch/dinov2/blob/main/dinov2/run/submit.py): SLURM submission · Submitit-style cluster launch flow. · `dinov2/run/submit.py`
- [Distributed and FSDP](https://github.com/facebookresearch/dinov2/blob/main/dinov2/distributed/__init__.py): execution runtime · Process setup and large-model sharding. · `dinov2/distributed/__init__.py`
- [Student-teacher SSL](https://github.com/facebookresearch/dinov2/blob/main/dinov2/train/ssl_meta_arch.py): meta architecture · Coordinates student and teacher ViT passes. · `dinov2/train/ssl_meta_arch.py`
- [DINO, iBOT, KoLeo losses](https://github.com/facebookresearch/dinov2/blob/main/dinov2/loss/dino_clstoken_loss.py): SSL objectives · Class-token distillation, masked patches, and regularization. · `dinov2/loss/dino_clstoken_loss.py`
- [Optimization loop](https://github.com/facebookresearch/dinov2/blob/main/dinov2/train/train.py): trainer · Optimizes SSL architecture and manages training state. · `dinov2/train/train.py`
- [Checkpoint persistence](https://github.com/facebookresearch/dinov2/blob/main/dinov2/utils/checkpoint.py): training state · Saves, resumes, and loads teacher checkpoints. · `dinov2/utils/checkpoint.py`

### Data pipeline

- [Datasets and loaders](https://github.com/facebookresearch/dinov2/blob/main/dinov2/data/loaders.py): input pipeline · Builds standard and microscopy dataset loaders. · `dinov2/data/loaders.py`
- [Multi-crop augmentation](https://github.com/facebookresearch/dinov2/blob/main/dinov2/data/augmentations.py): image transforms · Applies transforms, collation, and masking. · `dinov2/data/augmentations.py`
- [Microscopy adapters](https://github.com/facebookresearch/dinov2/blob/main/dinov2/data/datasets/cell_dino/chammi_hpa.py): channel-aware data · Cell-DINO datasets and channel transforms. · `dinov2/data/datasets/cell_dino/chammi_hpa.py`

### Evaluation and distribution

- [PyTorch Hub](https://github.com/facebookresearch/dinov2/blob/main/hubconf.py): public constructors · Stable torch.hub model interface. · `hubconf.py`
- **Model factories**: pretrained loaders · Standard, Cell-DINO, XRay-DINO, and DINO.txt factories.
- **External checkpoints**: model artifacts · Public or local pretrained weights.
- [Evaluation CLIs](https://github.com/facebookresearch/dinov2/blob/main/dinov2/run/eval/knn.py): downstream entry points · k-NN and linear-probe commands. · `dinov2/run/eval/knn.py`
- [Feature evaluators](https://github.com/facebookresearch/dinov2/blob/main/dinov2/eval/knn.py): k-NN and probes · k-NN, linear, logistic, and Cell-DINO evaluation. · `dinov2/eval/knn.py`
- [Dense task heads](https://github.com/facebookresearch/dinov2/blob/main/dinov2/eval/depth/models/builder.py): depth and segmentation · Depth, linear segmentation, and Mask2Former extensions. · `dinov2/eval/depth/models/builder.py`

## Connections

- PyTorch Hub → Model factories: exports
- Model factories → External checkpoints: loads weights
- Model factories → Vision Transformer: constructs
- Attention blocks → Vision Transformer: composes
- Multi-crop augmentation → Datasets and loaders: transforms batches
- Microscopy adapters → Datasets and loaders: extends
- Datasets and loaders → Student-teacher SSL: multi-crop batches
- Distributed training CLI → Cluster launcher: submits
- Distributed training CLI → Optimization loop: starts
- Cluster launcher → Distributed and FSDP: allocates workers
- Distributed and FSDP → Optimization loop: runs
- Student-teacher SSL → Vision Transformer: student and teacher
- Student-teacher SSL → DINO, iBOT, KoLeo losses: computes objectives
- DINO, iBOT, KoLeo losses → Optimization loop: gradients
- Optimization loop → Checkpoint persistence: saves/resumes
- Checkpoint persistence → Feature evaluators: teacher weights
- Evaluation CLIs → Feature evaluators: invokes
- Feature evaluators → Vision Transformer: extracts features
- Dense task heads → Vision Transformer: uses features
- Checkpoint persistence → Model factories: local weights
