> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/documentation/data/import-local-annotations.md).

# Import existing annotations

Import annotation JSON with local media or onto existing Unitlab project files. Prepare COCO and Unitlab exports, match file paths, and resolve import errors.

Open **Datasets → Upload → Local** in the destination project. Select media and annotation JSON together, or select only annotation JSON when the referenced media are already in the project.

![Project uploader in Local mode with Upload files and Upload folder](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FNJXR3WdaGIvNmIpIzGhj%2Fupload-media-and-labels.webp?alt=media)

Check that your deployment supports annotation imports and that you can manage data and create labels. The browser matches labels to the media you supply. To automate the same task, use [Python SDK annotation imports](https://docs.unitlab.ai/api-sdk-cli/sdks/annotation-imports). The CLI upload command transfers the media separately.

## Before you start

* Open the project that should receive the annotations. Confirm the project name before selecting files.
* Use a supported annotation format from the table below. Save valid UTF-8 JSON and keep each file below your deployment's upload request limit.
* Keep media references unique and consistent with the files you select or the existing project items. A filename appearing in two folders needs an unambiguous path or Unitlab file ID.

Annotation import runs in a project, not directly in the Asset library. For general media preparation and file support, see [Data upload](https://docs.unitlab.ai/documentation/data/data-upload.md).

Use an ordinary item in an **Annotate** or **Review** stage. Grouped tasks and items currently in **Model**, **Consensus**, or **Archive** cannot receive this import. Creating missing classes also requires **Manage classes** permission and a project-local ontology; imports cannot add classes to a shared ontology.

## Prepare media and labels together

The COCO file below is a file-matching exercise. It contains one illustrative **Car** box on a 1280 × 720 image named `road.jpg`. When using your own photograph, replace the example bounds with the reviewed bounds of a visible vehicle. Prepare the folder like this.

```
road-scenes/
├── images/
│   └── road.jpg
└── annotations.json
```

Save the [COCO example below](#example-coco-image-bounding-boxes) as `annotations.json`. Its `images[0].file_name` is `images/road.jpg`, exactly matching the path beneath `road-scenes/`. Select the whole `road-scenes` folder with **Upload folder**. Unitlab can account for the extra root-folder name added by the browser while preserving the referenced subfolder.

**Expected result:** one project image with one editable **Car** bounding box. Use your own media and update the filename, dimensions and coordinates together when adapting the example.

If the media are already in the project, select `annotations.json` alone. Ensure its references identify those existing items. Renaming files or dropping meaningful subfolder names can prevent matching or create ambiguity.

{% stepper %}
{% step %}

### Open the project's uploader

Go to the project's **Datasets** view and select **Upload**. In **Upload data**, select **Local**.
{% endstep %}

{% step %}

### Select annotations and media

Choose **Upload files** for annotation files and any new media, or **Upload folder** for a prepared directory. The picker accepts supported `.json` and `.geojson` alongside the media formats.

For labels on existing project data, select only the annotation files.
{% endstep %}

{% step %}

### Review the queue

Check that the queue contains `images/road.jpg` and `annotations.json` for this example. Use **Add more** if media are missing, or remove an incorrect file. Invalid JSON produces an error and must be corrected or removed before the upload can continue.
{% endstep %}

{% step %}

### Select Upload

Unitlab transfers new media, validates the annotation format, matches media and classes, and imports valid labels. The action reads **Importing labels…** while label import is running.

Complete any video frame or CSV configuration requested for the media. Files that still need processing can have their label import scheduled automatically.
{% endstep %}

{% step %}

### Review the imported result

Read the completion message, then open `road.jpg`. On a fresh import, expect one added **Car** box. Check its position and size against the image, then continue through your project's review process. Reimports can report kept or updated labels instead of a newly added label.
{% endstep %}
{% endstepper %}

## Supported annotation formats

<details>

<summary>Check supported formats and geometry</summary>

| Format                 | Expected structure                                                    | Use                                                                                 |
| ---------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **COCO**               | An object containing `images`, `categories`, and `annotations` arrays | Supported image annotations, or frame annotations with an explicit video frame map. |
| **Unitlab image JSON** | `schema_version` is `unitlab-image/1`                                 | Native image objects and whole-image select classifications.                        |
| **Unitlab video JSON** | `schema_version` is `unitlab-video/1`                                 | Native Unitlab video annotations and supported track information.                   |
| **UUEF item JSON**     | `version` is `1.0`, with a `media` object and a `labels` array        | Supported labels from an individual Unitlab Unified Export Format item.             |
| **Audio JSON**         | Contains `audio_files` and `categories` arrays                        | Supported labels from a Unitlab audio export.                                       |
| **GeoJSON**            | A `FeatureCollection` with a `features` array                         | Supported annotations from a Unitlab GeoJSON export.                                |

Use exports that retain the media identifiers, class definitions, and annotation fields required by their format. Recognition of a format does not mean every shape or custom extension is supported. Validation reports incompatible classes, unsupported annotations, and missing media.

UUEF import covers image, video, medical, audio, time series, PDF document, text, HTML, geospatial, and pathology labels. **Tabular and LiDAR/point-cloud annotation import are not supported by this importer.** UUEF group metadata does not recreate Data Groups. Top-level data tags, translations, and transcription are not restored by this label-import flow.

YOLO TXT, JSONL, arbitrary model-response JSON, and generic GeoJSON without Unitlab class/media metadata are not accepted label inputs.

Two companion formats have separate roles:

* **Frame mapping** uses `schema_version: "unitlab-frame-map/1"`. Upload it with exactly one COCO annotation JSON when frame images need to map to an existing video.
* **Package metadata** uses `schema_version: "unitlab-import-manifest/1"`. This is not a standalone annotation file or a generic data-upload manifest. Include the actual annotation JSON and media from the package.

A ZIP of annotations and images is not the Local annotation-import input. Extract the package and select its folder or supported files.

</details>

## Import predictions from your own model

<details>

<summary>Map model output to the import format</summary>

You can use supported model predictions as initial labels, then correct and review them in Unitlab:

| Model output                   | Prepare this format                                                                                                                               |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bounding boxes                 | COCO JSON or native `unitlab-image/1`, using `[x, y, width, height]` in original image pixels.                                                    |
| Polygons                       | COCO polygon `segmentation` or native `unitlab-image/1` polygon coordinates.                                                                      |
| Segmentation masks             | COCO RLE in `segmentation`, or a native `unitlab-image/1` mask annotation. Compressed counts strings and uncompressed integer runs are supported. |
| A category for the whole image | Native `unitlab-image/1` with an image-scope `single_select` or `multi_select` class and `classifications`.                                       |

COCO categories define object classes in this importer; they do not import image-wide classifications. Native image classifications appear under **Item properties** in the editor and can share a file with box or polygon annotations. See the complete [image-level classification example](https://docs.unitlab.ai/api-sdk-cli/sdks/annotation-imports#image-level-classification-example).

For COCO masks, use RLE with `size: [height, width]` matching the original image and `counts` covering the complete image in COCO column-major order. Polygon segmentation stays as polygons, while RLE segmentation becomes mask labels. A standalone mask PNG is not a label-import JSON file. See the [supported model-output structures](https://docs.unitlab.ai/api-sdk-cli/sdks/annotation-imports#import-predictions-from-your-own-model).

YOLO TXT labels are not supported directly. Convert YOLO detections or polygons to COCO or native image JSON, including the matching media references, class definitions and original pixel coordinates. See [model-output conversion guidance](https://docs.unitlab.ai/api-sdk-cli/sdks/annotation-imports#import-predictions-from-your-own-model). Changing the filename extension does not convert a label file.

</details>

## Download example annotation files

<details>

<summary>Choose a downloadable sample</summary>

These are small label-only examples. Supply matching media or adapt the references, dimensions, classes, and geometry to your own files before importing.

| Example                                   | Matching media                                      | Download                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Native image bounding box                 | `road.jpg`, 1280 × 720                              | [image-labels.json](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2Fp7V2zjCDUNy0wvpGApAk%2Fimage-labels.json?alt=media)                                                                                                                                                                                                                    |
| COCO image bounding box                   | `road.jpg`, 1280 × 720                              | [coco-labels.json](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FDjfguTjIDs6G2yml7TKB%2Fcoco-labels.json?alt=media)                                                                                                                                                                                                                      |
| Native video track on two explicit frames | `drive.mp4`, 1280 × 720, six source frames          | [video-labels.json](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FGVyeEYDVGrLMa3ghVUEh%2Fvideo-labels.json?alt=media)                                                                                                                                                                                                                    |
| COCO video frames with track IDs          | The same `drive.mp4`; labeled source frames 0 and 5 | [coco-video-labels.json](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FbvvXDt5JXwphL5uSojXR%2Fcoco-video-labels.json?alt=media) and [video-frame-map.json](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FlfH5XFA4cZ5BX2Qd6liU%2Fvideo-frame-map.json?alt=media) |

The COCO video pair uses `attributes.track_id`. Select both files together in the frontend. For programmatic import, use the corresponding track profile shown in the [SDK annotation guide](https://docs.unitlab.ai/api-sdk-cli/sdks/annotation-imports).

### Model-output examples

These label-only examples use `road.jpg` at 1280 × 720, or `mask-demo.png` at 4 × 3 for the small mask fixtures. Replace the references and coordinates with your own media before importing. The two mask files describe the same foreground pixels using different COCO encodings.

| Example                                          | Download                                                                                                                                                                                                           |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| COCO boxes and polygons                          | [coco-model-labels.json](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FEHKVzQgZzCydy13itfRS%2Fcoco-model-labels.json?alt=media)           |
| COCO mask, uncompressed RLE                      | [coco-mask-uncompressed.json](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FfEvfAQ2RPQh0KTJX49zY%2Fcoco-mask-uncompressed.json?alt=media) |
| COCO mask, compressed RLE                        | [coco-mask-compressed.json](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FRhJiwDcUKJD5MJvbRS2o%2Fcoco-mask-compressed.json?alt=media)     |
| Whole-image classification                       | [image-classification.json](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2Fi7Q2XagivGOxL1hjwOlK%2Fimage-classification.json?alt=media)     |
| Native boxes, polygons, and image classification | [model-image-labels.json](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FsKJTCtk5r6NRYXPtdNIL%2Fmodel-image-labels.json?alt=media)         |

</details>

## Example: COCO image bounding boxes

<details>

<summary>Open the sample COCO JSON</summary>

For the folder above, this compact COCO file describes one `Car` bounding box in `images/road.jpg`:

```json
{
  "images": [
    {
      "id": 1,
      "file_name": "images/road.jpg",
      "width": 1280,
      "height": 720
    }
  ],
  "categories": [
    {"id": 1, "name": "Car"}
  ],
  "annotations": [
    {
      "id": 1,
      "image_id": 1,
      "category_id": 1,
      "bbox": [100, 200, 300, 180],
      "area": 54000,
      "iscrowd": 0
    }
  ]
}
```

Replace the filename, dimensions, class, and coordinates with your own data. COCO bounding boxes use `[x, y, width, height]` in image pixels, with `x` and `y` at the top-left corner. Each annotation's `image_id` and `category_id` must reference entries in the same file. For another image, add an `images` entry with a unique ID and annotations that reference that ID.

Use coordinates from the original media, not a resized preview or normalized 0-to-1 coordinates. Annotation IDs must be unique within each media item. Image dimensions and other supplied media identity information must agree with the project file.

</details>

## Import COCO annotations onto video frames

<details>

<summary>See frame matching and a sample payload</summary>

For this separate example, prepare `drive.mp4` plus the downloadable COCO video labels and frame map from the table above:

```
video-example/
├── drive.mp4
├── coco-video-labels.json
└── video-frame-map.json
```

A COCO file containing frame images does not, by itself, identify the video or establish the frame indices. Use the `unitlab-frame-map/1` companion to map COCO image entries explicitly to the correct project video and frames.

For example, if a COCO annotation file contains image entries with IDs `100` and `105`, this companion maps them to original video frames 0 and 5:

```json
{
  "schema_version": "unitlab-frame-map/1",
  "frames": [
    {"coco_image_id": 100, "media_ref": "drive.mp4", "frame_index": 0},
    {"coco_image_id": 105, "media_ref": "drive.mp4", "frame_index": 5}
  ]
}
```

Frame-map indices start at **0**. Map every COCO image entry exactly once. The matching video must exist in the project, and its uploaded frame sampling must retain the referenced frames. For annotations on every original frame, select **Use native frame rate** when uploading the video, subject to the 60 fps limit.

Upload **one COCO annotation JSON and its one frame mapping JSON at a time**. Do not select several COCO files with a shared map or several possible maps in the same import. A frame mapping file without its COCO annotation file cannot import labels.

COCO `attributes.track_id` can supply track identities when supported by the mapped import. Independent frame annotations without a track identity should not be treated as continuous object tracks.

Native `unitlab-video/1` tracks also use explicit frame annotations. Their supported contract uses `presence_mode: "explicit_frames"` and `interpolation: "none"`; importing two labeled frames does not generate labels for the intervening frames.

</details>

## How matching and repeated imports work

<details>

<summary>Check how Unitlab matches an existing file or label</summary>

Unitlab matches incoming annotation references to the media in the current upload or to existing project data. For new media, the uploader uses the exact returned file IDs and relative paths so that another project file with the same basename does not silently receive the labels.

Use the full referenced subfolder path when needed. A media URL stored in JSON is a matching reference; the importer does not fetch that URL to upload a new file.

Classes are created or reused when compatible. A class mismatch blocks the affected import and explains the conflict. Correct the source format or class definition before retrying.

The browser flow preserves human edits and deletions. It does not automatically recreate a label you deleted or overwrite an edited label when incoming annotations conflict with it. It does not expose a bulk overwrite switch. Successfully imported files are marked complete so a retry does not apply them again within the same upload session. Removing a queued annotation file does not delete labels already saved to the project.

</details>

## Correct and review imported labels

<details>

<summary>Inspect the imported item and complete review</summary>

Imported labels are editable starting annotations. Importing does not mark a task complete or approve its labels, even if the source JSON contains an `approved` flag.

{% stepper %}
{% step %}

### Inspect and correct the result

Open each affected item in the annotation editor. Adjust boxes or polygon vertices, remove incorrect predictions and add missed objects. Check whole-image classifications under **Item properties**. Editing depends on your permissions and the item's workflow stage.
{% endstep %}

{% step %}

### Send the corrected item for review

Use a workflow with **Annotate** followed by **Review** when your team requires human approval. Select the available forward action, typically **Send to Review**, after checking the labels. Saving or importing labels alone does not perform this transition.
{% endstep %}

{% step %}

### Approve the work or return it for correction

The assigned reviewer inspects the annotations and makes permitted corrections. The forward action approves the review and follows the configured route; its label may be **Mark as Complete** or **Send to \[stage name]**. Select **Reject** to follow the configured rework route. Review assignment and self-review rules still apply.
{% endstep %}
{% endstepper %}

The browser import keeps conflicting human edits and deletions instead of overwriting them. For a deliberate change to protected work, use [SDK annotation imports](https://docs.unitlab.ai/api-sdk-cli/sdks/annotation-imports#correct-and-review-imported-predictions) to inspect conflicts and select an eligible Review destination. Grouped tasks and Model, Consensus and Archive remain unsupported import targets.

See [Review, rework and escalation](https://docs.unitlab.ai/documentation/workflows/review-rework-and-escalation) for the full workflow.

</details>

## Understand the result

<details>

<summary>Look up an import outcome or error</summary>

The completion message reports **Labels: N added · N updated · N kept · N skipped**. If imported boxes were clipped to the image boundaries, it also reports **Boxes clipped to image bounds**.

For media that are still processing, you may see **Labels from \[file] will be added when its media finish processing.** The page reports the scheduled import's success or failure when it settles. Return to the affected items and verify their annotations before using the data downstream.

For large annotation files, the application's parser ceiling and the deployment's request limit are different. The parser accepts up to 80 MiB, but a local transfer can be rejected below that size by the deployment. Split a rejected file into smaller valid annotation files, preserving media references and object identities, or import it from connected cloud storage. Prefer splitting by media item and keep each tracked object in one file. If one item's labels are too large for a local request, use connected cloud storage.

| Message or situation                                                | Resolution                                                                                                                                                                         |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **This file is not valid JSON**                                     | Correct the JSON syntax, then remove and reselect the corrected file.                                                                                                              |
| **Unsupported annotation JSON**                                     | Export a supported annotation format. A generic array of URLs, file paths, or task definitions is not accepted.                                                                    |
| **No matching media found**                                         | Include the referenced media in the upload or correct its path/identifier to match the project item.                                                                               |
| **Several project files match**                                     | Use a unique file path or Unitlab file ID.                                                                                                                                         |
| More than one uploaded file matches                                 | Make the reference unique while retaining its subfolder information.                                                                                                               |
| A class or annotation is incompatible                               | Read the validation error and correct the source class or unsupported shape.                                                                                                       |
| **Add the COCO annotation JSON that belongs to this frame mapping** | Select the map and its single COCO companion together.                                                                                                                             |
| A file is rejected for size                                         | Keep it below the deployment's request limit and parser ceiling. Split it into smaller valid files with complete references and class definitions, or use connected cloud storage. |
| Transfer or import stops                                            | Check the error and pending queue. Correct the problem, then select **Upload** to retry.                                                                                           |

</details>

## Continue with the data

* Use [Data upload](https://docs.unitlab.ai/documentation/data/data-upload.md) for supported source media and processing steps.
* Use [Data Groups and layouts](https://docs.unitlab.ai/documentation/data/data-groups-and-layouts.md) for the separate workflow that groups source files in the Asset library.
* See [Export formats and source inclusion](https://docs.unitlab.ai/documentation/releases/export-formats-and-source-inclusion.md) when preparing annotations for reuse or downstream training.
* For scripted validation, explicit mappings, and controlled commits, use [SDK annotation imports](https://docs.unitlab.ai/api-sdk-cli/sdks/annotation-imports).

***

> **Continue with Unitlab:** [data annotation platform](https://unitlab.ai/en/data-annotation)

## Complete the workflow

See [Pre-labels, review, and export](https://docs.unitlab.ai/api-sdk-cli/sdks/prelabels-review-and-export) for the full S3, import, human review, and delivery workflow.
