Supervisely SDK for Python


Computer Vision Platform, Open Ecosystem of Apps, SDK for Python

Package version Docker Pulls
PyPI - Python Version Slack Package version


Supervisely Ecosystem:

Dev Documentation:

Source Code of SDK for Python:

Supervisely Ecosystem on GitHub:

Complete video course on YouTube: What is Supervisely?

Table of contents


Every company wants to be sure that its current and future AI tasks are solvable.

The main issue with most solutions on the market is that they build as products. It’s a black box developing by some company you don’t really have an impact on. As soon as your requirements go beyond basic features offered and you want to customize your experience, add something that is not in line with the software owner development plans or won’t benefit other customers, you’re out of luck.

That is why Supervisely is building a platform instead of a product.

Supervisely Platform 🔥

Supervisely Platform

You can think of Supervisely as an Operating System available via Web Browser to help you solve Computer Vision tasks. The idea is to unify all the relevant tools within a single Ecosystem of apps, tools, UI widgets and services that may be needed to make the AI development process as smooth and fast as possible.

More concretely, Supervisely includes the following functionality:

  • Data labeling for images, videos, 3D point cloud and volumetric medical images (dicom)

  • Data visualization and quality control

  • State-Of-The-Art Deep Learning models for segmentation, detection, classification and other tasks

  • Interactive tools for model performance analysis

  • Specialized Deep Learning models to speed up data labeling (aka AI-assisted labeling)

  • Synthetic data generation tools

  • Instruments to make it easier to collaborate for data scientists, data labelers, domain experts and software engineers

Supervisely Ecosystem 🎉

Supervisely Platform

The simplicity of creating Supervisely Apps has already led to the development of hundreds of applications, ready to be run within a single click in a web browser and get the job done.

Label your data, perform quality assurance, inspect every aspect of your data, collaborate easily, train and apply state-of-the-art neural networks, integrate custom models, automate routine tasks and more — like in a real AppStore, there should be an app for everything.

Development 🧑‍💻

Supervisely provides the foundation for integration, customization, development and running computer vision applications to address your custom tasks - just like in OS, like Windows or MacOS.

What developers can do

There are different levels of integration, customization, and automation:


  2. Python scripts for automation and integration

  3. Headless apps (without UI)

  4. Apps with interactive UIs

  5. Apps with UIs integrated into labeling tools


Supervisely has a rich HTTP REST API that covers basically every action, you can do manually. You can use any programming language and any development environment to extend and customize your Supervisely experience.

ℹ️ For Python developers, we recommend using our Python SDK because it wraps up all API methods and can save you a lot of time with built-in error handling, network re-connection, response validation, request pagination, and so on.

cURL example

There’s no easier way to kick the tires than through cURL. If you are using an alternative client, note that you are required to send a valid header in your request.


curl -H "x-api-key: <your-token-here>"

As you can see, URL starts with It is for Community Edition. For Enterprise Edition you have to use your custom server address.

Level 2. Python scripts for automation and integration

Supervisely SDK for Python is specially designed to speed up development, reduce boilerplate, and lets you do anything in a few lines of Python code with Supervisely Annotatation JSON format, communicate with the platform, import and export data, manage members, upload predictions from your models, etc.

Python SDK example

Look how it is simple to communicate with the platform from your python script.

import supervisely as sly

# authenticate with your personal API token
api = sly.Api.from_env()

# create project and dataset
project = api.project.create(workspace_id=123, name="demo project")
dataset = api.dataset.create(, "dataset-01")

# upload data
image_info = api.image.upload_path(, "img.png", "/Users/max/img.png")
api.annotation.upload_path(, "/Users/max/ann.json")

# download data
img = api.image.download_np(
ann = api.annotation.download_json(

Level 3. Headless apps (without UI)

Create python apps to automate routine and repetitive tasks, share them within your organization, and provide an easy way to use them for end-users without coding background. Headless apps are just python scripts that can be run from a context menu.

run app from context menu

It is simple and suitable for the most basic tasks and use-cases, for example:

Level 4. Apps with interactive UIs

Interactive interfaces and visualizations are the keys to building and improving AI solutions: from custom data labeling to model training. Such apps open up opportunities to customize Supervisely platform to any type of task in Computer Vision, implement data and models workflows that fit your organization’s needs, and even build vertical solutions for specific industries on top of it.

[This interface is completely based on python in combination with easy-to-use Supervisely UI widgets (Batched SmartTool app for AI assisted object segmentations)

Here are several examples:

Level 5. Apps with UI integrated into labeling tools

There is no single labeling tool that fits all tasks. Labeling tool has to be designed and customized for a specific task to make the job done in an efficient manner. Supervisely apps can be smoothly integrated into labeling tools to deliver amazing user experience (including multi tenancy) and annotation performance.

[AI assisted retail labeling app is integrated into labeling tool and can communicate with it via web sockets)

Here are several examples:

  • apps designed for custom labeling workflows (example1, example2)

  • NN inference is integrated for labeling automation and model predictions analysis (example)

  • industry-specific labeling tool: annotation of thousands of product types on shelves with AI assistance (retail collection, labeling app)

Principles 🧭

Development for Supervisely builds upon these five principles:

  • All in pure Python and build on top of your favourites libraries (opencv, requests, fastapi, pytorch, imgaug, etc …) - easy for python developers and data scientists to build and share apps with teammates and the ML community.

  • No front‑end experience is required - build powerful and interactive web-based GUI apps using the comprehensive library of ready-to-use UI widgets and components.

  • Easy to learn, fast to code, and ready for production. SDK provides a simple and intuitive API by having complexity “under the hood”. Every action can be done just in a few lines of code. You focus on your task, Supervisely will handle everything else - interfaces, databases, permissions, security, cloud or self-hosted deployment, networking, data storage, and many more. Supervisely has solid testing, documentation, and support.

  • Everything is customizable - from labeling interfaces to neural networks. The platform has to be customized and extended to perfectly fit your tasks and requirements, not vice versa. Hundreds of examples cover every scenario and can be found in our ecosystem of apps.

  • Apps can be both open-sourced or private. All apps made by Supervisely team are open-sourced. Use them as examples, just fork and modify the way you want. At the same time, customers and community users can still develop private apps to protect their intellectual property.

Main features 💎

Start in a minute

Supervisely’s open-source SDK and app framework are straightforward to get started with. It’s just a matter of:

pip install supervisely

Magically simple API

Supervisely SDK for Python is simple, intuitive, and can save you hours. Reduce boilerplate and build custom integrations in a few lines of code. It has never been so easy to communicate with the platform from python.

# authenticate with your personal API token
api = sly.Api.from_env()

# create project and dataset
project = api.project.create(workspace_id=123, name="demo project")
dataset = api.dataset.create(, "dataset-01")

# upload data
image_info = api.image.upload_path(, "img.png", "/Users/max/img.png")
api.annotation.upload_path(, "/Users/max/ann.json")

# download data
img = api.image.download_np(
ann = api.annotation.download_json(

Customization is everywhere

Customization is the only way to cover all tasks in Computer Vision. Supervisely allows to customizing everything from labeling interfaces and context menus to training dashboards and inference interfaces. Check out our Ecosystem of apps to find inspiration and examples for your next ML tool.

Interactive GUI is a game-changer

The majority of Python programs are “command line” based. While highly experienced programmers don’t have problems with it, other tech people and end-users do. This creates a digital divide, a “GUI Gap”. App with graphic user interface (GUI) becomes more approachable and easy to use to a wider audience. And finally, some tasks are impossible to solve without a GUI at all.

Imagine, how it will be great if all ML tools and repositories have an interactive GUI with the RUN button ▶️. It will take minutes to start working with a top Deep Learning framework instead of spending weeks running it on your data.

🎯 Our ambitious goal is to make it possible.

Semantic segmentation metrics app

Develop fast with ready UI widgets

Hundreds of interactive UI widgets and components are ready for you. Just add to your program and populate with the data. Python devs don’t need to have any front‑end experience, in our developer portal you will find needed guides, examples, and tutorials. We support the following UI widgets:

  1. Widgets made by Supervisely specifically for computer vision tasks, like rendering galleries of images with annotations, playing videos forward and backward with labels, interactive confusion matrices, tables, charts, …

  2. Element widgets - Vue 2.0 based component library

  3. Plotly Graphing Library for Python

  4. You can develop your own UI widgets (example)

Supervisely team makes most of its apps publically available on GitHub. Use them as examples for your future apps: fork, modify, and copy-paste code snippets.

Convenient debugging

Supervisely is made by data scientists for data scientists. We trying to lower barriers and make a friendly development environment. Especially we care about debugging as one of the most crucial steps.

Even in complex scenarios, like developing a GUI app integrated into a labeling tool, we keep it simple - use breakpoints in your favorite IDE to catch callbacks, step through the program and see live updates without page reload. As simple as that! Supervisely handles everything else - WebSockets, authentication, Redis, RabitMQ, Postgres, …

Watch the video below, how we debug the app that applies NN right inside the labeling interface.

Apps can be both private and public

All apps made by Supervisely team are open-source. Use them as examples: find on GitHub, fork and modify them the way you want. At the same time, customers and community users can still develop private apps to protect their intellectual property.

Single-click deployment

Supervisely app is a git repository. Just provide the link to your git repo, Supervisely will handle everything else. Now you can press Run button in front of your app and start it on any computer with Supervisely Agent.

Reliable versioning - releases and branches

Users run your app on the latest stable release, and you can develop and test new features in parallel - just use git releases and branches. Supervisely automatically pull updates from git, even if the new version of an app has a bug, don’t worry - users can select and run the previous version in a click.

Supports both Github and Gitlab

Since Supervisely app is just a git repository, we support public and private repos from the most popular hosting platforms in the world - GitHub and GitLab.

App is just a web server, use any technology you love

Supervisely SDK for Python provides the simplest way for python developers and data scientists to build interactive GUI apps of any complexity. Python is a recommended language for developing Supervisely apps, but not the only one. You can use any language or any technology you love, any web server can be deployed on top of the platform.

For example, even Visual Studio Code for web can be run as an app (see video below).

Built-in cloud development environment (coming soon)

In addition to the common way of development in your favorite IDE on your local computer or laptop, cloud development support will be integrated into Supervisely and released soon to speed up development, standardize dev environments, and lower barriers for beginners.

How will it work? Just connect your computer to your Supervisely instance and run IDE app (JupyterLab and Visual Studio Code for web) to start coding in a minute. We will provide a large number of template apps that cover the most popular use cases.

Trusted by Fortune 500. Used by 65 000 researchers, developers, and companies worldwide

Supervisely helps companies and researchers all over the world to build their computer vision solutions in various industries from self-driving and agriculture to medicine. Join our Community Edition or request Enterprise Edition for your organization.

Community 🌎

Join our constantly growing Supervisely community with more than 65k+ users.

Have an idea or ask for help?

If you have any questions, ideas or feedback please:

  1. Suggest a feature or idea, or give a technical feedback

  2. Join our slack

  3. Contact us

Your feedback 👍 helps us a lot and we appreciate it

Contribution 👏

Want to help us bring Computer Vision R&D to the next level? We encourage you to participate and speed up R&D for thousands of researchers by

  • building and expanding Supervisely Ecosystem with us

  • integrating to Supervisley and sharing your ML tools and research with the entire ML community

Partnership 🤝

We are happy to expand and increase the value of Supervisely Ecosystem with additional technological partners, researchers, developers, and value-added resellers.

Feel free to contact us if you have

  • ML service or product

  • unique domain expertise

  • vertical solution

  • valuable repositories and tools that solve the task

  • custom NN models and data

Let’s discuss the ways of working together, particularly if we have joint interests, technologies and customers.

Cite this Project

If you use this project in a research, please cite it using the following BibTeX:

@misc{ supervisely,
    title = { Supervisely Computer Vision platform },
    type = { Computer Vision Tools },
    author = { Supervisely },
    howpublished = { \url{ } },
    url = { },
    journal = { Supervisely Ecosystem },
    publisher = { Supervisely },
    year = { 2023 },
    month = { jul },
    note = { visited on 2023-07-20 },