Install & Compatibility
Where this runs
tested against v2.1.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 23.0s · import 0.570s · 451MB
458MB installed
● package 458MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from label_studio_sdk import Client
Project
✓ from label_studio_sdk.objects import Project
✗ from label_studio_sdk.client 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`.
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.")
Errors
Common errors & fixes
requests.exceptions.ConnectionError: HTTPConnectionPool(host='localhost', port=8080): Max retries exceeded with url: /api/something (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x...>: Failed to establish a new connection: [Errno 111] Connection refused'))
The Label Studio server or ML backend is not running, is running on a different host/port, or is inaccessible from where the SDK script is executed (e.g., due to Docker networking or incorrect URL).
fixEnsure the Label Studio server is running and accessible at the specified `base_url`. If running the SDK script from within a Docker container and Label Studio is on the host, use `http://host.docker.internal:PORT` or the host's explicit IP address instead of `localhost` for the `base_url`.
requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: http://your-label-studio-url/api/projects "detail": "Invalid token."
The provided API key is incorrect, expired, or the wrong type of token (e.g., using a Personal Access Token when a Legacy Token is required, or vice versa, especially with ML backends). The `base_url` might also be incorrectly formatted (e.g., includes a trailing slash or an API path).
fixVerify the API key from your Label Studio 'Account & Settings' or 'Organization > Access Token Settings.' Ensure the correct type of token (Legacy vs. Personal) is used for the specific integration (ML backends sometimes require Legacy Tokens). Also, confirm the `base_url` does not have a trailing slash or an API endpoint appended (e.g., `http://localhost:8080`, not `http://localhost:8080/` or `http://localhost:8080/api`).
TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'
The `label-studio-sdk` uses Python 3.10+ specific syntax for union types (e.g., `dict | None`), but the script is being executed with an older Python version (e.g., 3.9 or earlier).
fixUpgrade your Python environment to Python 3.10 or a newer version to support the required syntax.
ModuleNotFoundError: No module named 'label_studio_sdk'
The `label-studio-sdk` library is not installed in the Python environment where the code is being executed.
fixpip install label-studio-sdk
label_studio_sdk.exceptions.APIError: 401 Unauthorized
The provided Label Studio URL or API key is incorrect, expired, or the user token lacks the necessary permissions to access the API.
fixclient = Client(url='YOUR_CORRECT_LABEL_STUDIO_URL', api_key='YOUR_VALID_API_KEY') # Ensure URL is correct and includes http/https, and the API key is active and has appropriate permissions.
Upgrade
Version history
2.1.1latest on PyPI · released Aug 10, 2026
Audit
Dependencies
requestsrequiredHTTP client for API communication.
pydanticrequiredUsed for data validation and parsing API responses into models.
PillowrequiredFor image processing related to data handling.
python-dotenvrequiredFor loading environment variables (e.g., API keys) from .env files.