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

# Label Sets - BETA

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

A **label set** is a named, reusable definition of which labels in a Project you want to version. Each time you create a **version** of a label set, Encord freezes the labels that match the set's selection, at their current revision, into a numbered snapshot (`v1`, `v2`, `v3`, and so on). Annotation keeps going on the Project, but a version never changes, so you can export it today or in six months and get the same labels.

Use label sets when you need to answer questions like:

* "Which exact labels did we train model v3 on?"
* "How many labels did the team add between last month's delivery and this one?"
* "Can I re-export the dataset we delivered to the customer in March?"

> [!NOTE]
>
> When label sets are enabled for your Organization, the **Export** button in the Project header is replaced by a **Versioning** button. The previous export flow is still available from the **Export (legacy)** tab in the Versioning drawer.

For a comparison of label sets with label branches, Label Checkpoint stages, prediction branches, and saved versions, see [Choosing How to Version Labels](https://docs.encord.com/platform-documentation/Annotate/annotate-export/annotate-label-versioning-compared.md).

## Key Concepts

| Concept | Description |
| - | - |
| **Label set** | A named configuration that belongs to one Project. It defines *which* labels to capture. A label set does not hold labels itself. |
| **Selection** | The rule that decides which labels a version captures: every label on the Project's `main` branch, or only the labels in one Workflow stage. The selection is applied each time you create a version, so later versions pick up newly added labels. |
| **Version** | A frozen, numbered snapshot of the labels that matched the selection when the version was created. Versions are numbered automatically, and you can optionally give each one a name. |
| **Trigger** | When versions are created. Versions are currently created manually (**Manual only**). |

A label set always reads from the Project's `main` branch. Labels on other branches (for example Consensus branches, Label Checkpoint branches, or prediction branches) are not captured.

## Who Can Use Label Sets

| Action | Required role |
| - | - |
| Open the **Versioning** drawer, create and edit label sets, create versions, and export versions | Project Admin |

## Create a Label Set

1. Open the Project.
2. Click **Versioning** in the Project header.
   The *Versioning* drawer opens on the **Label sets** tab. If the Project has no label sets yet, the drawer shows *No versioning configured* and the **Versioning** button shows a warning dot.
3. Click **Create label set**. If the Project already has a label set, click **New label set** instead.
4. In the *New label set* dialog, specify the following:
   * **Name**: A meaningful name, for example `Vehicle detection` or `Customer delivery`.
   * **Which labels to capture**: Select one of:
     * **Every label on the main branch**: Captures all labels in the Project, regardless of where their tasks are in the Workflow.
     * **Only labels in a workflow stage**: Captures only the labels on tasks that are in the Workflow stage you select. For example, select your **Complete** stage to capture only finished, approved labels.
5. Click **Create label set**.

The label set appears in the drawer with the message *No versions yet*.

> [!TIP]
>
> You can create several label sets on the same Project, each with a different selection. For example, one set that captures every label for progress tracking, and another that captures only the **Complete** stage for model training.

## Create a Version

Creating a version freezes the labels that the set currently selects.

1. Click **Versioning** in the Project header.
2. Find the label set and click **Create version**.
   The dialog summarizes what the version will capture, for example *Captures labels in Complete. Those labels are frozen into the new version.*
3. Optionally, enter a **Version name**, for example `Training run 2026-11`. If you leave the name blank, the version is named after its number, for example `v4`.
4. Click **Create version**.

The new version appears at the top of the version history with the **Latest** tag.

> [!WARNING]
>
> A version cannot be created when no labels match the set's selection. Encord displays the error *No labels match the selection, so there is nothing to cut*. Check that the selected Workflow stage contains labeled tasks, or change the selection.

## Read the Version History

Each label set card shows the set's versions, newest first. For each version you see:

* The version number (`v1`, `v2`, ...) and its name, if you gave it one.
* The number of labels the version holds, or its status: *Capturing…* while the version is being built, or *Capture failed* if it could not be built.
* The date the version was created.
* A **Manual** tag for versions you created manually, and a **Latest** tag on the newest version that is ready to export.

Above the list, a bar shows the size of each version relative to the others. Hover over a segment, or over a row in the list, to see the version's label count, how many labels were added or removed compared with the previous version, and when it was added.

## Export a Version

You can export any version that has finished capturing.

1. Click **Versioning** in the Project header.
2. Find the version in the label set's version history and click **Export**.
3. In the *Export* dialog, specify the following:
   * **Format**: JSON or COCO.
   * **Generate signed URLs**: Specify whether to generate signed URLs for the data units. Enabling this option can significantly increase export times.
   * **Data group label format**: **New** or **Legacy**. See [Data Group Label Format Options](https://docs.encord.com/platform-documentation/Annotate/annotate-export/annotate-how-to-export-labels.md#data-group-label-format-options).
4. Click **Export**.

A version always exports **every** label it froze, including labels that use Ontology features that were archived after the version was created. The Workflow stage and **Labels to include** options do not appear, because the version's contents are fixed.

The export ZIP file contains the labels in the format you selected, plus a `label_set_version.json` manifest that records which label set and version the export came from:

```json label_set_version.json theme={"dark"}
{
  "label_set": {
    "id": "<label-set-id>",
    "name": "Vehicle detection",
    "description": "",
    "origin": "workflow"
  },
  "version": {
    "id": "<version-id>",
    "version_number": 4,
    "name": "Training run 2026-11",
    "cut_at": "2026-11-03T10:15:00+00:00",
    "cut_by": "<user>",
    "label_count": 12840
  },
  "sources": [
    {
      "captured_source_id": "<id>",
      "source_type": "project_branch",
      "project_hash": "<project-id>"
    }
  ]
}
```

Store the manifest with your training data so you can always trace a model back to the exact version of the labels it used.

## Edit a Label Set

1. Click **Versioning** in the Project header.
2. Click **Edit configuration** on the label set.
3. Change the **Name** or the **Which labels to capture** selection.
4. Click **Save**.

Changes apply to the **next** version you create. Existing versions are never changed.

> [!NOTE]
>
> If a label set's selection was configured outside the app with filters the drawer cannot display (for example, a list of specific data units or a title search), the drawer shows a description of the selection instead of the radio buttons, and the selection cannot be changed from the UI.

## Limitations

* **One Project, `main` branch only.** A label set captures labels from the `main` branch of a single Project.
* **Manual versions only.** Scheduled versions (for example, every 24 hours or every 1,000 completed tasks) are not yet available. A label set's trigger shows **Manual only**.
* **Data groups.** Versions cannot yet be created for Projects that contain Data Groups. Encord displays the error *This project contains data groups, which versions cannot capture yet*.
* **SDK.** Label sets cannot yet be created, versioned, or exported using the SDK. To snapshot labels programmatically, [copy labels to a branch](https://docs.encord.com/sdk-documentation/sdk-labels/sdk-label-versioning.md).

## Best Practices

* **Version what you deliver.** Point a label set at your final Workflow stage (usually **Complete**) and create a version every time you hand labels to a model team or a customer.
* **Name versions after the event, not the date.** The date is already recorded. A name like `Customer delivery 3` or `Model v3 training` is easier to find later.
* **Keep the manifest.** The `label_set_version.json` file in every export is your audit trail.
* **Use separate label sets for separate purposes** rather than changing the selection on one set. A set whose selection keeps changing produces versions that are hard to compare.


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