How to import annotations

You can import annotations to all project types. The annotations you upload should follow the SuperAnnotate annotation format, whose structure is based on JSON.

Annotation file format

Before you upload annotation files, make sure they have a valid file format. The annotation files should have the following naming conventions:

Project type

Annotation file naming conventiononvention










When you upload annotations, make sure that their corresponding items are available in the project. If they aren’t, then the annotations won’t be uploaded.


  • The annotations you upload override the existing annotations.
  • When you upload an annotation, the item's status will be changed to inProgress.

Annotation format

SuperAnnotate supports the SuperAnnotate annotation format and other common annotation formats (COCO, YOLO, and VOC).

To use the common annotation formats, you need to convert the annotations to the SuperAnnotate annotation format first.

The structure of the SuperAnnotate annotation format is based on JSON. Here are the formats of imported annotations:

Upload annotations from local storage

To upload annotations from a local directory:

    project = "Car Project",
    folder_path = "./data/annotations")

To enable recursive subfolder upload (when annotations are stored within multiple subfolders) set recursive_subfolders to true:

    project = "Car Project",
    folder_path = "./data/annotations", 
    recursive_subfolders = True)


When you upload annotations, the status of an item will change to inProgress.

Upload annotations from a cloud storage

AWS S3 Bucket

To upload annotations from an AWS S3 bucket:

    project = "Car Project",
    folder_path = "./data/annotations",
    from_s3_bucket = "Car Bucket")


  • Make sure that you have your AWS creditials for the from_s3_bucket argument.
  • When you upload annotations, the status of an item will change to inProgress.

Identify invalid annotations

When you want to upload annotations from a folder, the function will identify the invalid annotations and show you a warning message that contains the number of invalid annotations.

The function will also put the paths of invalid annotations to the return tuple of (uploaded, could-not-upload, missing-images), in the could-not-upload list accordingly.

Use the function below to fetch the possible reason(s) for why an annotation is invalid.

     project_type = “Video”, 
     annotations_json = “./<video_name.json>”)

Add annotation instances

You can add annotation instances to items in Vector Projects only.

To add a Point to an item:

    project = "Project Name",
    image_name = "image_name.png", 
    point = [100, 200],
    annotation_class_name = "Class Name")

To add a Bounding Box to an item:

    project = "Project Name", 
    image_name = "image_name.png",
    bbox = [100, 200, 300, 500],
    annotation_class_name = "Class Name")


Add a Bounding Box by setting its top-right and bottom-left coordinates in the bbox field.


When you add annotations, the status of an item will change to inProgress.

Did this page help you?