Getting started


SuperAnnotate Python SDK is available on PyPI. Use the following command on your terminal to install our SDK.

pip install superannotate

The latest version supports Python 3.7 + and was tested under Linux and Windows (Anaconda) platforms.

You need to install the ffmpeg package for certain video-related functions to work. It can be installed on Ubuntu with the following command:

sudo apt-get install ffmpeg

To use the consensus functions on Windows and Mac platforms, you might also need to install the shapely package beforehand. The package works well only under the Anaconda distribution with:

conda install shapely

Initialization and authorization

To use the SDK, you need to create a config file with a team-specific authentication token. The token is available to Team Admins on the Team Settings page.

SAClient can be used without arguments

Without arguments

from superannotate import SAClient
sa_client = SAClient()

Method 1: SA_TOKEN is defined as an environment variable.

Method 2: Generate a default location (~/.superannotate/config.ini) config file. CLI init should be used:

superannotatecli init --token <token>
                      [--logging_level <NOTSET/INFO/DEBUG/WARNING/ERROR/CRITICAL (Default=INFO)>]
                      [--logging_path <Default=/Users/username/.superannotate/logs>]

With arguments

Method 1: Use the token as an argument

from superannotate import SAClient

Method 2: Create a custom config file

from superannotate import SAClient
sa_client = SAClient(config_path="~/.superannotate/dev-config.ini")

Custom config.ini example:

SA_TOKEN = <token>
LOGGING_PATH = /Users/username/data/superannotate_logs

Class SAClient

Create the SAClient instance to authorize SDK in a team scope. If no argument is provided, the SA_TOKEN environmental variable will be automatically checked, or $HOME/.superannotate/config.json will be used.

# To instantiate SAClient using the team token:

team_1 = SAClient(
    token = "48c828b33e1a2a92fcdfccd54ecfebde1a1b787c741dd34935fe6c00430d80e78156c181c6e79759t=12759"

# To instantiate SAClient using the path to the config file that contains the team token:
team_1 = SAClient(config_path = "~/.superannotate/config.json")

# No arguments:

team_1 = SAClient()

To get the name of the team you've instantiated the instance for:


To create an SAClient instance for another team in parallel (using another config.json file/token):

team_2 = SAClient(config_path = "~/.superannotate/2_config.json")

To get the name of the other team you've instantiated an SAClient for: