Label Studio SDK

2.0.19 · active · verified Sat Apr 11

The `label-studio-sdk` is the official Python client library for interacting with the Label Studio API. It provides programmatic access to manage projects, tasks, annotations, import/export data, and automate various data labeling workflows. It is currently at version 2.0.19 and maintains a regular release cadence with frequent updates adding new features and API endpoint support.

Warnings

breaking The SDK underwent a significant overhaul from v1.x to v2.x, introducing numerous breaking changes in client initialization, method names, object structures, and pagination handling. Code written for v1.x will not work with v2.x.
Fix: Refer to the official migration guide for updating your code to use the v2.x API client: https://labelstud.io/guide/sdk_migrate_v1_v2/
breaking Starting from v2.0.13, the `project` argument became a required parameter for all Import and Export Storage list endpoints (e.g., S3, Google Cloud Storage, Azure Blob Storage).
Fix: Ensure you pass a valid `project` ID when calling these storage list endpoints, for example: `ls.get_s3_import_storages(project=your_project_id)`.
gotcha Some advanced features and API endpoints, particularly those related to Finite State Management (FSM) or Workspace management, are exclusive to Label Studio Enterprise (LSE). Attempts to use them with the Community Edition will result in API errors.
Fix: Verify that the feature you are trying to use is supported by your Label Studio edition. Check the official Label Studio documentation for feature availability per edition.
gotcha For large datasets, methods that retrieve lists of resources (e.g., tasks, annotations, members) may require explicit pagination to fetch all items. The SDK provides mechanisms to iterate through pages.
Fix: Consult the SDK documentation for specific methods and their pagination arguments (e.g., `page_size`, `page`). You may need to loop through results until all pages are retrieved.

Install

pip install label-studio-sdk Install latest version

Imports

Client
```
from label_studio_sdk import Client
```
Project
```
from label_studio_sdk.objects import Project
```
Project objects are typically accessed via the Client instance (e.g., `ls.get_projects()[0]`) or from `label_studio_sdk.objects` directly, not `client`.

Quickstart

Initializes the Label Studio client, connects to your instance, and lists all available projects. Ensure `LABEL_STUDIO_URL` and `LABEL_STUDIO_API_KEY` are set either as environment variables or directly in the code.

import os
from label_studio_sdk import Client

# Set your Label Studio URL and API Key
# It's recommended to set these as environment variables
LABEL_STUDIO_URL = os.environ.get('LABEL_STUDIO_URL', 'http://localhost:8080')
LABEL_STUDIO_API_KEY = os.environ.get('LABEL_STUDIO_API_KEY', 'YOUR_API_KEY_HERE') # Replace with your actual API key if not in env

if not LABEL_STUDIO_API_KEY or LABEL_STUDIO_API_KEY == 'YOUR_API_KEY_HERE':
    print("Warning: LABEL_STUDIO_API_KEY not set. Please set it as an environment variable or replace 'YOUR_API_KEY_HERE'.")
    exit()

try:
    # Initialize the Label Studio client
    ls = Client(url=LABEL_STUDIO_URL, api_key=LABEL_STUDIO_API_KEY)
    
    # Test connection and fetch projects
    projects = ls.get_projects()
    print(f"Successfully connected to Label Studio at {LABEL_STUDIO_URL}.")
    print(f"Found {len(projects)} projects:")
    for p in projects:
        print(f"  - Project ID: {p.id}, Title: {p.title}")

except Exception as e:
    print(f"Error connecting to Label Studio or fetching projects: {e}")
    print("Please ensure LABEL_STUDIO_URL and LABEL_STUDIO_API_KEY are correct and Label Studio is running.")

view raw JSON →