> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encord.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning Labels

Encord offers several ways to keep more than one state of a Project's labels. They solve different problems, and they work well together. This page explains what each one is for, how they differ, and which to use.

> [!NOTE]
>
> Label sets are currently in BETA and are not available to every Organization. Contact your Encord representative to enable label sets for your Organization. Label Checkpoint stages, label branches, prediction branches, and saved versions are available to all Organizations.

| Method | In one sentence |
| - | - |
| [**Label sets (BETA)**](#label-sets-beta) | Freeze the Project's labels into numbered, read-only versions that you can compare and re-export at any time. |
| [**Label Checkpoint stage**](#label-checkpoint-stage-and-label-branches) | Copy each task's labels to a named branch automatically as the task moves through the Workflow. |
| [**Prediction branches**](#prediction-branches) | Keep model predictions on their own branch, separate from human labels. |
| [**Saved versions (legacy)**](#saved-versions-legacy) | Save a named snapshot as a side effect of a manual export. |

## At a Glance

| | **Label sets (BETA)** | **Label Checkpoint / label branches** | **Prediction branches** | **Saved versions (legacy)** |
| - | - | - | - | - |
| **What it holds** | Human labels from `main` that match the set's selection | A copy of each task's labels at the moment it passed the stage | Model output, marked as predictions with confidence scores | The labels included in one export |
| **Created by** | **Create version** in the Versioning drawer | Tasks passing through a Label Checkpoint stage, or `copy_labels_to_branch()` in the SDK | Your import script or a Pre-labeling Agent, using the SDK | Selecting **Save as new version** when exporting |
| **Granularity** | Whole label set, all at once | One task at a time | One data unit at a time | Whole export, all at once |
| **Can it change later?** | No. Versions are frozen | Yes. Re-entry can overwrite, and the SDK can write to the branch | Yes | No |
| **Numbered history and change tracking** | Yes (`v1`, `v2`, ... with label counts and +/- per version) | No | No | No (a flat list of names) |
| **Reusable configuration** | Yes. The selection is saved and reapplied for each version | Yes. The stage is part of the Workflow | Not applicable | No. Options are chosen per export |
| **View in the Label Editor** | No | Yes, with the **Branches** overlay | Yes, with the **Branches** overlay | No |
| **Export from the UI** | Yes, from the Versioning drawer, with a `label_set_version.json` manifest | No, export with the SDK | No, export with the SDK | Yes |
| **SDK support** | Not yet | Yes (`branch_name`) | Yes (`branch_name`) | Export only |
| **Best for** | Training datasets, customer deliveries, audits | Preserving labels before rework, comparing passes, QA | Model evaluation and pre-labeling | Existing pipelines that already use it |

## Label Sets (BETA)

A [label set](https://docs.encord.com/platform-documentation/Annotate/annotate-export/annotate-label-sets.md) is a saved rule (for example, "every label in the **Complete** stage") that you can capture again and again. Each capture is a numbered, read-only **version**. Versions show how many labels they hold and how many were added or removed since the previous version, and you can export any version at any time with exactly the same result.

**Use label sets when:**

* You need to reproduce exactly which labels a model was trained on.
* You deliver labels in rounds and want a record of each delivery.
* You want to track how much a labeled dataset grows between milestones.

**Keep in mind:**

* Label sets are in BETA and must be enabled for your Organization.
* Label sets read only from the `main` branch of one Project.
* Versions cannot be opened in the Label Editor. Export a version to inspect it.
* Versions are created manually from the UI. SDK support is not yet available.

## Label Checkpoint Stage and Label Branches

A [Label Checkpoint stage](https://docs.encord.com/platform-documentation/Annotate/annotate-projects/annotate-workflows-and-templates.md#label-checkpoint) is a Workflow stage. Every task that passes through it has its labels copied to the branch you name in the stage, for example `pre-review` or `annotator-pass-1`. Unlike a label set version, which captures the whole Project at once, a checkpoint captures each task individually, at the moment that task reaches the stage.

The **On re-entry** setting controls what happens when a task passes through the stage again: **Skip** keeps the first copy, **Overwrite** replaces it.

You can also create a branch from the SDK with [`copy_labels_to_branch()`](https://docs.encord.com/sdk-documentation/sdk-labels/sdk-label-versioning).

**Use a Label Checkpoint stage when:**

* You want to keep the annotator's original labels before Review changes them, and compare the two in the Label Editor with the [**Branches** overlay](https://docs.encord.com/platform-documentation/Annotate/annotate-label-editor/annotate-label-editor-review.md#view-label-branches).
* You want to measure how much labels change between Workflow stages.
* You need a per-task snapshot that fills up automatically as work flows through the Project.

**Keep in mind:**

* A branch is a working copy, not a frozen version. With **Overwrite**, or with SDK writes, its contents change.
* Branch labels are exported using the SDK, by passing `branch_name` to `list_label_rows_v2()`. See [Export Labels](https://docs.encord.com/sdk-documentation/sdk-labels/sdk-export.md).
* Label sets do not read from checkpoint branches. They read from `main`.

## Prediction Branches

Prediction branches hold **model output**, not human labels. You write predictions to a branch using the SDK by passing `branch_name` to `list_label_rows_v2()`, and marking each label with `manual_annotation=False` and a `confidence` score. See [Import Predictions](https://docs.encord.com/platform-documentation/Validation/active-how-to/active-import-model-predictions-cloud.md).

**Use prediction branches when:**

* You want to evaluate a model against your ground truth labels in the Project's **Explore** tab.
* A [Pre-labeling Agent](https://docs.encord.com/sdk-documentation/sdk-labels/sdk-label-versioning.md) writes predictions that you want to review before they reach `main`.
* You want to see predictions next to human labels in the Label Editor with the **Branches** overlay.

**Keep in mind:**

* Predictions are not a version of your labels. They are a separate set of labels from a different source.
* To turn validated predictions into labels, copy them to `main` with `copy_labels_to_branch(..., target_branch="main", overwrite=True)`. Once they are on `main`, they can be captured by a label set.

## Saved Versions (Legacy)

Before label sets, the only way to keep a snapshot from the UI was to select **Save as new version** in the *Export labels* dialog. Encord saves the labels included in that export under the name you provide. Saved versions are listed in **Settings > Saved versions**, where you can export or delete them. When label sets are enabled, saved versions are also listed in the **Export (legacy)** tab of the Versioning drawer.

**Keep in mind:**

* A saved version captures whatever that one export included. The export options (stage, labels to include) are not saved, so the next saved version may capture something different.
* Saved versions have no version numbers, no label count history, and no manifest describing where they came from.
* Use label sets for new work. Saved versions remain available so that existing exports and pipelines keep working.

## Which Should I Use?

| I want to... | Use |
| - | - |
| Know exactly which labels trained a model, and re-export them later | Label sets |
| Deliver labels to a customer in rounds and keep a record of each round | Label sets |
| Track how many labels were added between milestones | Label sets |
| Keep the annotator's labels before a reviewer edits them | Label Checkpoint stage |
| Compare two labeling passes side by side in the Label Editor | Label Checkpoint stage, then the **Branches** overlay |
| Snapshot labels from a script | `copy_labels_to_branch()` in the SDK |
| Evaluate a model against ground truth | Prediction branch |
| Pre-label data without disturbing annotators' work on `main` | Prediction branch (or a Pre-labeling Agent) |
| Export the current state of the labels once, with no need to reproduce it | **Export (legacy)**, or an [Export stage](https://docs.encord.com/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels.md#export-labels-to-cloud-storage-recommended) for continuous delivery to cloud storage |

## Using Them Together

These methods complement each other. A typical Project might use all of them:

1. A **Pre-labeling Agent** writes model output to a `pre-labels` **prediction branch**. Validated predictions are copied to `main` for annotators to correct.
2. A **Label Checkpoint stage** after Annotate copies each task's labels to an `annotator-pass` branch, so reviewers and QA leads can compare before and after Review.
3. A **label set** that captures the **Complete** stage is versioned every time labels are handed to the model team. Each export includes the `label_set_version.json` manifest, so every model can be traced to a label set version.

## Moving from Saved Versions to Label Sets

If label sets are enabled for your Organization and you currently select **Save as new version** on each export:

1. [Create a label set](https://docs.encord.com/platform-documentation/Annotate/annotate-export/annotate-label-sets.md#create-a-label-set) whose selection matches the stage you usually export from.
2. Instead of exporting with **Save as new version**, click **Create version** on the label set, then **Export** on the new version.
3. Keep your existing saved versions. They remain available in the **Export (legacy)** tab and in **Settings > Saved versions**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.