Supervisely Python SDK

Warnings

• breaking Supervisely SDK versions are tied to the Supervisely instance version. Using an incompatible SDK version with your platform instance can lead to unexpected errors or missing functionality.
  Fix: Refer to the Supervisely Developer Portal's 'App Compatibility' or 'Installation' section to ensure your SDK version is compatible with your Supervisely instance. It's recommended to keep both updated.
• gotcha Directly embedding API tokens in your source code (`sly.Api(token='...')`) is highly discouraged for security reasons, especially in production environments. While convenient for quick tests, it exposes sensitive credentials.
  Fix: Always use environment variables (`os.environ`) or `.env` files (loaded with `python-dotenv`) to store `API_TOKEN` and `SERVER_ADDRESS`, and initialize the API client with `sly.Api.from_env()`.
• deprecated The `supervisely_lib` package was an earlier module structure. Direct imports from `supervisely_lib` are now deprecated and may cause `ModuleNotFoundError` or lead to outdated behavior in recent SDK versions.
  Fix: Always use `import supervisely as sly` and access sub-modules directly from `sly` (e.g., `sly.api.project_api`). Refer to the latest SDK documentation for correct import paths.
• gotcha When developing scripts or applications that modify data, accidentally altering active projects is a common mistake. This can lead to data loss or corruption in production datasets.
  Fix: Always clone projects for development and testing purposes. The SDK provides methods for cloning projects to ensure your original data remains safe.
• gotcha Users deploying Supervisely agents or applications with GPU acceleration might encounter 'Failed to initialize NVML' or 'CUDA Out Of Memory' errors, often related to NVIDIA driver issues or Docker configurations.
  Fix: Troubleshoot NVIDIA driver issues, ensure proper Docker runtime configuration (e.g., `nvidia-container-runtime`), and manage memory allocation for GPU-intensive tasks. Rebooting the machine or restarting Docker can often resolve transient NVML errors.

Install

• pip install supervisely Install latest version

Imports

• Api

  import supervisely as sly
  api = sly.Api.from_env()

  The `supervisely_lib` package was used in older versions but is now deprecated. Always use `import supervisely as sly`.
• Project, Dataset, ImageInfo

  from supervisely.project.project import Project
  from supervisely.project.dataset import Dataset
  from supervisely.api.image_api import ImageInfo

  Many core classes are nested within submodules. Refer to the SDK documentation for specific import paths.

Quickstart

This quickstart demonstrates how to establish an API connection to the Supervisely platform using recommended authentication practices via environment variables and verifies the connection by listing available teams. For production, always use environment variables for secrets.

import os
import supervisely as sly

# It is highly recommended to set SERVER_ADDRESS and API_TOKEN as environment variables.
# For Community Edition, SERVER_ADDRESS is typically 'https://app.supervisely.com'
# For Enterprise Edition, use your custom instance address.
SERVER_ADDRESS = os.environ.get('SERVER_ADDRESS', 'https://app.supervisely.com')
API_TOKEN = os.environ.get('API_TOKEN', 'YOUR_SUPERVISELY_API_TOKEN_HERE') # Replace with your actual token or ensure env var is set

# Initialize API client from environment variables (recommended)
# For local development, you might use a .env file loaded with dotenv.
# See: https://developer.supervisely.com/getting-started/basics-of-authentication
try:
    api = sly.Api(server_address=SERVER_ADDRESS, token=API_TOKEN)
    
    # Test authentication by fetching teams
    my_teams = api.team.get_list()
    print(f"Successfully connected to Supervisely. You are a member of {len(my_teams)} team(s).")
    
    if my_teams:
        team = my_teams[0]
        print(f"First team: {team.name} (ID: {team.id})")
        workspaces = api.workspace.get_list(team.id)
        if workspaces:
            print(f"First workspace in team '{team.name}': {workspaces[0].name} (ID: {workspaces[0].id})")
        else:
            print(f"No workspaces found in team '{team.name}'.")
    else:
        print("No teams found for the provided API token. Please check your credentials and permissions.")

except Exception as e:
    print(f"Error connecting to Supervisely API: {e}")
    print("Please ensure SERVER_ADDRESS and API_TOKEN environment variables are correctly set.")