Comment on page
Intro to Python SDK
Let's try Supervisely SDK for Python and create your first python script for Supervisely automation.
In this example we will show you how it is easy to communicate with your Supervisely instance (Community or your private Enterprise installation) from python code. The tutorial illustrates basic upload-download scenario:
- create project and dataset on server
- upload image
- programmatically create annotation (two bounding boxes and tag) and upload it to image
- download image and annotation
You can try this example for yourself: VSCode project config, original image, and python script for this tutorial are ready on GitHub.
Watch the video tutorial here:
Video tutorial for beginners - introduction to Supervisely SDK for python developers
pip install supervisely

Input image preview
Import Supervisely, initialize API with your credentials and test authentication (learn the basics of authentication here). In this example, we use the server address of Community Edition. Change it if you have a private instance of Supervisely.
import json
import supervisely as sly
api = sly.Api(server_address="https://app.supervise.ly", token="4r47N...xaTatb")
my_teams = api.team.get_list()
print(f"I'm a member of {len(my_teams)} teams")
# get first team and workspace
team = my_teams[0]
workspace = api.workspace.get_list(team.id)[0]
Let's create an empty project
animals
with one dataset cats
, then one class cat
of shape Rectangle and one tag scene
with string value and upload them into the project. Now we can use created classes and tags for labeling.project = api.project.create(workspace.id, "animals", change_name_if_conflict=True)
dataset = api.dataset.create(project.id, "cats", change_name_if_conflict=True)
print(f"Project {project.id} with dataset {dataset.id} are created")
cat_class = sly.ObjClass("cat", sly.Rectangle, color=[0, 255, 0])
scene_tag = sly.TagMeta("scene", sly.TagValueType.ANY_STRING)
project_meta = sly.ProjectMeta(obj_classes=[cat_class], tag_metas=[scene_tag])
api.project.update_meta(project.id, project_meta.to_json())
Let's upload local image
images/my-cats.jpg
to dataset.image_info = api.image.upload_path(dataset.id, name="my-cats.jpg", path="images/my-cats.jpg")
cat1 = sly.Label(sly.Rectangle(top=875, left=127, bottom=1410, right=581), cat_class)
cat2 = sly.Label(sly.Rectangle(top=549, left=266, bottom=1500, right=1199), cat_class)
tag = sly.Tag(scene_tag, value="indoor")
ann = sly.Annotation(img_size=[1600, 1200], labels=[cat1, cat2], img_tags=[tag])
api.annotation.upload_ann(image_info.id, ann)
img = api.image.download_np(image_info.id) # RGB ndarray
print("image shape (height, width, channels)", img.shape)
ann_json = api.annotation.download_json(image_info.id)
print("annotaiton:\n", json.dumps(ann_json, indent=4))
In less than 50 lines of code (including lots of comments) you can easily automate Supervisely using Python and integrate it with your software stack.
That’s just a taste of what you can do with the Supervisely SDK for Python. For more, take a look at the reference and Supervisely Annotation JSON format.

Result in labeling tool