Install & Compatibility
Where this runs
tested against v6.74.32 · 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 31.9s · import 0.000s · 807MB
817MB installed
● package 817MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Api
✓ import supervisely as sly
api = sly.Api.from_env()
✗ import supervisely_lib as sly
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.
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.")
Debug
Known issues
breakingSupervisely 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.fixRefer 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.
affects: All versions
gotchaDirectly 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.fixAlways 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()`.
affects: All versions
deprecatedThe `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.fixAlways 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.
affects: <=6.x.x (exact version unknown, but prior to current structure)
gotchaWhen 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.fixAlways clone projects for development and testing purposes. The SDK provides methods for cloning projects to ensure your original data remains safe.
affects: All versions
gotchaUsers 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.fixTroubleshoot 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.
affects: All versions utilizing GPU features
Upgrade
Version history
6.74.32latest on PyPI · released Aug 28, 2026
Audit
Dependencies
pythonrequiredRequired Python version.