Skip to main content
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.
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.

At a Glance

Label Sets (BETA)

A label set 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 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(). 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.
  • 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.
  • 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. 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 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?

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 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.