> ## 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. Label sets require version 0.2.0 or later of the `encord` SDK.

A **label set** defines 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. Versions never change, so you can always trace a model or a delivery back to the exact labels it used.

For an introduction to label sets in the Encord app, see [Label Sets](https://docs.encord.com/platform-documentation/Annotate/annotate-export/annotate-label-sets.md). To compare label sets with label branches, Label Checkpoint stages, 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 | In the SDK | Description |
| - | - | - |
| **Label set** | [`LabelSet`](https://docs.encord.com/sdk-documentation/sdk-references/label_set) | A named definition of which labels to capture. A label set does not hold labels itself. |
| **Source** | [`ProjectSource`](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set) | The Project branch a label set reads. Use `main` for the labels made in the Project, or another branch for labels written from outside the Project, such as model predictions. |
| **Selection** | `AllSelection`, `WorkflowStageSelection` | Which labels on the branch a version captures: every label (the default), or only the labels on tasks in specific Workflow stages. Stage selections apply to the `main` branch only. |
| **Origin** | `LabelSetOrigin` | Where the branch's labels come from. `WORKFLOW` for labels made in the Project, `IMPORT` for predictions and other labels written to the branch from outside. |
| **Version** | [`LabelSetVersion`](https://docs.encord.com/sdk-documentation/sdk-references/label_set) | A frozen, numbered snapshot of the labels that matched the selection when the version was created. |

## Permissions

| Action | Required role on the source Project |
| - | - |
| List and read label sets and their versions | Any role |
| Create label sets, change them, create versions, and export versions | Admin or Team Manager |

Organization Admins, and users with a custom Organization role that can manage all Projects, can also perform these actions.

## Limitations

* **One source.** A label set reads one branch of one Project.
* **Stage selections on `main` only.** Workflow tasks exist on the `main` branch only, so a `WorkflowStageSelection` cannot be used on any other branch.
* **Manual versions only.** Versions are created when you call `create_version_job()`. Scheduled versions are not available.
* **Data Groups.** Versions cannot yet be created for Projects that contain Data Groups.

## Versions Are Created by Jobs

Creating and exporting a version can take a while, so both run as jobs:

1. `create_version_job()` (or `create_export_job()`) queues the job and returns its ID straight away.
2. `get_version_job()` (or `get_export_job()`) reads the job's state. Pass `timeout_seconds` to wait for the job to finish. With the default of `0`, the method reads the state once and returns.

A job's state is one of the following:

| State | Meaning |
| - | - |
| `LabelSetJobPending` | The job is queued or running. Read it again later. Waiting never cancels a job. |
| `VersionJobDone` / `VersionExportJobDone` | The job finished. A version job returns the new version's `version_id`. An export job returns a `signed_url` to download the export. |
| `VersionJobFailed` / `VersionExportJobFailed` | The job failed. A failed version job explains why in `error`, and no version is created. |
| `LabelSetJobUnknown` | A state that your version of the SDK does not recognize. Upgrade the `encord` package. |

## Create a Label Set and a Version

The following example creates a label set that captures the labels on tasks in the **Complete** stage of a Project's Workflow, and then creates its first version. Each version you create later captures the tasks that are in the stage at that time.

To capture every label on the `main` branch instead, leave out `label_selection`.

```python Create a label set and a version theme={"dark"}

# Import dependencies
from uuid import UUID

from encord.orm.label_set import (
    LabelSetOrigin,
    ProjectSource,
    VersionJobDone,
    VersionJobFailed,
    WorkflowStageSelection,
)
from encord.user_client import EncordUserClient

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the unique Project ID
LABEL_SET_NAME = "Customer delivery"  # Replace with a name for the label set
STAGE_NAME = "Complete"  # Replace with the Workflow stage whose labels you want to capture
VERSION_NAME = "Customer delivery 1"  # Replace with a name for the version, or set to None to use its number

# Create user client using SSH key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Specify Project and find the Workflow stage to capture
project = user_client.get_project(PROJECT_ID)
stage = project.workflow.get_stage(name=STAGE_NAME)

# 1. Create a label set that captures the labels on tasks in the stage.
# Leave out label_selection to capture every label on the main branch instead.
label_set = user_client.create_label_set(
    LABEL_SET_NAME,
    sources=[
        ProjectSource(
            project_id=UUID(PROJECT_ID),
            branch_name="main",
            label_selection=WorkflowStageSelection(workflow_stage_ids=[stage.uuid]),
        )
    ],
    description=f"Labels in the {STAGE_NAME} stage",
    origin=LabelSetOrigin.WORKFLOW,
)
print(f"Created label set {label_set.name} ({label_set.id})")

# 2. Queue a version and wait up to 10 minutes for it to finish
job_id = label_set.create_version_job(VERSION_NAME)
job = label_set.get_version_job(job_id, timeout_seconds=600)

if isinstance(job, VersionJobDone):
    version = label_set.get_version(job.version_id)
    print(f"Version {version.version_number} ({version.name}) holds {version.label_count} labels")
elif isinstance(job, VersionJobFailed):
    print(f"No version was created: {job.error}")
else:
    print(f"Still running. Check again later with label_set.get_version_job('{job_id}')")

```

> [!WARNING]
>
> A version cannot be created when no labels match the selection. The version job fails, and `VersionJobFailed.error` explains why.

## Version Model Predictions

To keep a frozen record of each model run, write the model's predictions to a dedicated branch of the Project, and create a label set with `origin=LabelSetOrigin.IMPORT` that reads that branch. Each time the model runs, replace the predictions on the branch and create a new version.

The following example writes predictions to the `preds/model-7` branch, creates a label set for the branch, and creates a version of the predictions. For more information on importing predictions, see [Import Predictions](https://docs.encord.com/platform-documentation/Validation/active-how-to/active-import-model-predictions-cloud.md).

```python Upload predictions and create a version theme={"dark"}

# Import dependencies
from uuid import UUID

from encord.orm.label_set import LabelSetOrigin, ProjectSource, VersionJobDone, VersionJobFailed
from encord.user_client import EncordUserClient

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the unique Project ID
BRANCH_NAME = "preds/model-7"  # One branch per model. The label set captures this branch.
LABEL_SET_NAME = "Model 7"  # Replace with a name for the label set
VERSION_NAME = "run 12"  # Replace with a name for this run's version
BUNDLE_SIZE = 100  # Customize as needed

# Create user client using SSH key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Specify Project
project = user_client.get_project(PROJECT_ID)
assert project is not None, f"Project with ID {PROJECT_ID} could not be loaded"

# 1. Initialise the label rows on the branch, creating a row where none exists yet
label_rows = project.list_label_rows_v2(branch_name=BRANCH_NAME)
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for label_row in label_rows:
        label_row.initialise_labels(bundle=bundle)

# 2. Replace what is on each row with this run's predictions and save.
# initialise_labels() also loads the previous run, so clear it first or the version holds both runs.
with project.create_bundle(bundle_size=BUNDLE_SIZE) as bundle:
    for label_row in label_rows:
        for object_instance in label_row.get_object_instances():
            label_row.remove_object(object_instance)
        for classification_instance in label_row.get_classification_instances():
            label_row.remove_classification(classification_instance)
        # Add the model's output to the row here, for example:
        # instance = project.ontology_structure.get_child_by_title("Car").create_instance()
        # instance.set_for_frames(BoundingBoxCoordinates(...), frames=0, confidence=0.93, manual_annotation=False)
        # label_row.add_object_instance(instance)
        label_row.save(bundle=bundle)

# 3. Create a label set that reads the branch.
# Use LabelSetOrigin.IMPORT for labels written to the branch from outside Encord, such as predictions.
label_set = user_client.create_label_set(
    LABEL_SET_NAME,
    sources=[ProjectSource(project_id=UUID(PROJECT_ID), branch_name=BRANCH_NAME)],
    origin=LabelSetOrigin.IMPORT,
)

# 4. Queue a frozen version of the predictions and wait for it
job_id = label_set.create_version_job(VERSION_NAME)
job = label_set.get_version_job(job_id, timeout_seconds=600)
if isinstance(job, VersionJobDone):
    version = label_set.get_version(job.version_id)
    print(f"Version {version.version_number} holds {version.label_count} labels")
elif isinstance(job, VersionJobFailed):
    print(f"No version was created: {job.error}")
else:
    print(f"Still running. Check again later with label_set.get_version_job('{job_id}')")

# For later runs of the same model, repeat steps 1, 2, and 4 on the same branch and label set.
# Each run becomes a new version. Give a new model its own branch and its own label set.

```

> [!WARNING]
>
> `initialise_labels()` loads the labels from the previous run, so remove them before you add the new predictions. Otherwise the new version holds the labels from both runs.

## List Label Sets, Versions, and Labels

`list_label_sets()` returns the label sets you can see, newest first. Pass `project_id` to list only the label sets that a Project feeds. `list_versions()` returns a label set's versions, newest first, and `list_members()` returns the labels a version holds, each at the revision it captured.

```python List label sets, versions, and labels theme={"dark"}

# Import dependencies
from itertools import islice

from encord.orm.label_set import LabelSetVersionStatus, StoredProjectSource
from encord.user_client import EncordUserClient

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the unique Project ID
MAX_LABELS = 10  # Number of labels to print for each version. Remove the cap to list every label.

# Create user client using SSH key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# List the label sets that the Project feeds, newest first
for label_set in user_client.list_label_sets(project_id=PROJECT_ID):
    print(f"Label set: {label_set.name} ({label_set.id}), origin: {label_set.origin.name}")

    # Each source is the Project branch the label set reads
    for source in label_set.sources:
        if isinstance(source, StoredProjectSource):
            print(f"  Source: Project {source.project_id}, branch '{source.branch_name}'")

    # List the versions of the label set, newest first
    for version in label_set.list_versions():
        print(
            f"  Version {version.version_number} '{version.name}': {version.status.name}, "
            f"{version.label_count} labels, created {version.capture_started_at:%Y-%m-%d} by {version.created_by_email}"
        )
        if version.status != LabelSetVersionStatus.READY:
            continue

        # List the labels the version holds, at the revision it captured
        for member in islice(version.list_members(), MAX_LABELS):
            print(f"    {member.data_title}: label {member.label_id}, revision {member.label_version}")

```

> [!TIP]
>
> Label sets returned by `list_label_sets()` do not include each source's selection. Call `label_set.refetch_data()` before you read a source's `label_selection_mode`.

To get the Ontology that a version's labels were made against, as it was when the version was created, call `version.get_ontology()`.

## Change a Label Set

Use `update()` to change a label set's name or description, and `set_label_selection()` to change which labels the **next** version captures. Existing versions are never changed.

```python Rename a label set and change its selection theme={"dark"}

# Import dependencies
from encord.orm.label_set import AllSelection, StoredProjectSource, WorkflowStageSelection
from encord.user_client import EncordUserClient

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your SSH private key
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the unique Project ID
LABEL_SET_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the unique label set ID
STAGE_NAME = "Review 1"  # Replace with the Workflow stage to capture, or set to None to capture every label

# Create user client using SSH key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

label_set = user_client.get_label_set(LABEL_SET_ID)

# Change the name and description. Arguments you leave out are unchanged.
label_set.update(name="Reviewed labels", description="Labels that passed the first review")

# Change which labels the next version captures. Existing versions are never changed.
source = label_set.sources[0]  # A label set has one source
if not isinstance(source, StoredProjectSource):
    raise ValueError("This SDK version cannot read the label set's source. Upgrade the encord package.")

if STAGE_NAME is None:
    label_set.set_label_selection(source.id, AllSelection())
else:
    project = user_client.get_project(PROJECT_ID)
    stage = project.workflow.get_stage(name=STAGE_NAME)
    # Stage selections apply to the main branch only
    label_set.set_label_selection(source.id, WorkflowStageSelection(workflow_stage_ids=[stage.uuid]))

print(f"{label_set.name}: next version captures {label_set.sources[0]}")

```

## Export a Version

You can export any version whose status is `READY`, in JSON or COCO format. The export is a ZIP file that holds the labels and a `label_set_version.json` manifest that records which label set and version the export came from. For details of the manifest, see [Export a Version](https://docs.encord.com/platform-documentation/Annotate/annotate-export/annotate-label-sets.md#export-a-version).

The download link is valid for seven days. Each time you call `get_export_job()`, you get a new link.

```python Export a version theme={"dark"}

# Import dependencies
from pathlib import Path

import requests

from encord.orm.label_set import ExportFormat, VersionExportJobDone, VersionExportJobFailed
from encord.user_client import EncordUserClient

# User input
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your SSH private key
LABEL_SET_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the unique label set ID
VERSION_ID = None  # Replace with the unique version ID, or leave as None to export the newest version
EXPORT_FORMAT = ExportFormat.JSON  # ExportFormat.JSON or ExportFormat.COCO
OUTPUT_DIR = Path("label-set-exports")  # Replace with the folder to save the export to

# Create user client using SSH key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

label_set = user_client.get_label_set(LABEL_SET_ID)

# Get the version to export. list_versions() returns the newest version first.
if VERSION_ID is None:
    version = next(label_set.list_versions(), None)
    if version is None:
        raise ValueError(f"Label set {label_set.name} has no versions yet")
else:
    version = label_set.get_version(VERSION_ID)

# Queue the export and wait up to 30 minutes for it to finish
job_id = version.create_export_job(EXPORT_FORMAT)
job = version.get_export_job(job_id, timeout_seconds=1800)

if isinstance(job, VersionExportJobDone):
    # Download the ZIP archive. It holds the labels and a label_set_version.json manifest.
    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
    output_path = OUTPUT_DIR / f"{label_set.name}-v{version.version_number}-{EXPORT_FORMAT.name.lower()}.zip"
    with requests.get(job.signed_url, stream=True, timeout=300) as response:
        response.raise_for_status()
        with open(output_path, "wb") as f:
            for chunk in response.iter_content(chunk_size=1024 * 1024):
                f.write(chunk)
    print(f"Saved version {version.version_number} of {label_set.name} to {output_path}")
elif isinstance(job, VersionExportJobFailed):
    print("The export failed. Queue it again, and contact Encord support if it fails again.")
else:
    print(f"Still running. Check again later with version.get_export_job('{job_id}')")

```


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