Project backup and portability
Use "Export project" to produce a .zip containing the complete project — every dataset, all media, every annotation, the label and task configuration and the per-project settings — and "Import project" to restore it on any machine. This archive is AnnotateIt’s own format, not COCO or YOLO; it exists to move a whole project, while a dataset export exists to feed a training pipeline.
Why this matters more here than elsewhere
AnnotateIt is local-first: there is no server holding a copy of your work, which is the entire point and also the trade-off. Nothing syncs. If the device is lost, reinstalled or wiped, the projects on it are gone. Backup is a thing you do, not a thing that happens.
Export a project archive whenever you have done work you would not want to redo. It is the only copy that exists outside the app’s local storage.
What is in a project archive
- Every dataset in the project, not just the one you are looking at.
- All media — images and video — embedded in the archive rather than referenced.
- Every annotation, including annotations on video frames.
- Native video tracks — keyframes and interpolation — kept as tracks, not flattened to per-frame boxes.
- The label structure and the project’s single task configuration.
- The per-project settings.
Structurally it is a .zip holding one JSON manifest (annotateit-project.json) plus one binary entry per media file under media/. The manifest carries the project — its task, labels, settings, every annotation, video-frame annotations and native tracks — while the media bytes sit beside it as their own entries rather than being base64-inlined into the JSON. That keeps the manifest small and the whole round trip lossless: the media travel inside the same archive.
Format version
The manifest has exactly one supported contract: format version 2. Its root, project and task objects accept only the current keys, the project carries one scalar domain and one task, and those domains must be known and equal. The task label ids must exactly match the project labels, keypoint structure is required only for a keypoint project, and every annotation, review marker and native track must reference that same label set. A missing or unsupported version, an unsupported field, a broken reference or an inconsistent task schema is rejected before the project is materialised. The one act of compatibility: a legacy format-version-1 archive is still accepted and normalised to version 2 on import — beyond that there is no compatibility reader or partial fallback.
Import always creates a separate copy. The project, datasets, media, labels, task, annotations and tracks receive fresh internal ids, and every reference is rewritten through the same remapping tables. Video frame numbers remain positions in the video, not database ids.
Project archive versus dataset export
| Project archive | Dataset export | |
|---|---|---|
| Purpose | Move or back up a whole project | Feed a training pipeline |
| Scope | Every dataset, media, settings, labels and the single task | One dataset, in a standard format |
| Format | AnnotateIt-specific JSON manifest in a .zip | COCO, YOLO, Pascal VOC, Datumaro, Supervisely Video, MOT, KITTI, MOTS or plain ZIP |
| Readable by other tools | No | Yes — that is the point |
| Round trip back into AnnotateIt | Lossless | Depends on format; Datumaro preserves the most |
If you want both — an archive is not a substitute for an export, and an export is not a substitute for a backup. Use the archive for safety and for moving machines; use a dataset export for training and for handing data to another tool.
Moving a project to another machine
- Export the project from the source machine. Large projects take a while: all media are embedded, so the archive is roughly the size of the media it contains.
- Copy the .zip across — a drive, a share, anything. There is no account and no cloud step, so this is a plain file transfer.
- On the target machine, use Import project and select the archive.
- The project arrives complete, with fresh internal ids. Nothing needs to be reconnected.
Backing up everything at once
A project archive covers one project. When what you actually want is "this machine, as it stands", Settings → Backup writes the whole local profile to a single .zip: the database behind every project, every media blob and its thumbnail, the custom models you imported, and the device-level settings. Restoring it on another install brings the lot back.
- Export runs entirely in memory and is refused up front, with a sentence, if the profile is larger than the device can package — rather than being discovered half-way through by the tab dying.
- It can be cancelled while it runs, and a cancelled export leaves no partial file: nothing is written until the archive is complete.
- Restore offers to export the current profile first, because importing one replaces what is already there.
- The archive carries a format version and a signature, so a file that is not a profile backup is refused rather than half-read.
| Project archive | Profile backup | |
|---|---|---|
| Scope | One project | Every project, plus imported models and app settings |
| Use it to | Move or share a single project | Move a whole workstation, or sleep at night |
| Size | Roughly the project’s media | Roughly everything on the device |
| Selective restore | Yes — import one project into an existing install | No — it replaces the profile |
Dataset versions are a separate thing
Inside a project, dataset versions and history let you snapshot, compare and restore the state of a dataset. They are available on every tier including free. They live on the device with everything else, though — so they are a working history, not a backup. A project archive, or a profile backup, is still what protects you from losing the device.