Import & Export Datasets

CVAT provides flexible options for importing annotations and exporting datasets in various formats. You can work with datasets through the web interface, command-line tools, or programmatically using the SDK.

Export Datasets

Exporting allows you to download your annotated data in formats compatible with popular machine learning frameworks and tools.

Export via Web UI

Navigate to your task or project
Click the Actions menu (three dots)
Select Export dataset
Choose your desired format from the dropdown
Toggle Save images if you want to include image data
Click OK to start the export

The export runs as a background job. You’ll receive a notification when it’s ready to download.

Export via CLI

The CVAT CLI provides the export-dataset command for tasks:

# Export task in COCO format
cvat-cli --auth user:password task export-dataset \
  --format "COCO 1.0" \
  --output /path/to/dataset.zip \
  123

# Export in YOLO format without images
cvat-cli task export-dataset \
  --format "YOLO 1.1" \
  --output yolo_annotations.zip \
  --no-images \
  123

# Export Pascal VOC format with images
cvat-cli task export-dataset \
  --format "PASCAL VOC 1.1" \
  --output voc_dataset.zip \
  123

Common options:

--format: Annotation format (see supported formats)
--output: Output file path
--no-images: Export annotations only, exclude images

Export via SDK

The Python SDK provides programmatic access to export functionality:

import cvat_sdk
from pathlib import Path

# Connect to CVAT server
with cvat_sdk.make_client(
    host="https://app.cvat.ai",
    credentials=("username", "password")
) as client:
    # Get task by ID
    task = client.tasks.retrieve(123)
    
    # Export dataset in COCO format with images
    task.export_dataset(
        format_name="COCO 1.0",
        filename="coco_dataset.zip",
        include_images=True
    )
    
    print("Export completed!")

Advanced SDK export examples:

# Export multiple formats
formats = ["YOLO 1.1", "COCO 1.0", "PASCAL VOC 1.1"]

for fmt in formats:
    output_name = fmt.replace(" ", "_").lower() + ".zip"
    task.export_dataset(
        format_name=fmt,
        filename=output_name,
        include_images=False
    )
    print(f"Exported {fmt} to {output_name}")

# Export with progress tracking
from cvat_sdk.core.progress import SimpleProgressReporter

pbar = SimpleProgressReporter()
task.export_dataset(
    format_name="COCO 1.0",
    filename="dataset.zip",
    include_images=True,
    pbar=pbar
)

# Export to cloud storage
from cvat_sdk.core.proxies.types import Location

task.export_dataset(
    format_name="YOLO 1.1",
    filename="yolo_dataset.zip",
    location=Location.CLOUD_STORAGE,
    cloud_storage_id=5
)

Export parameters:

format_name: Format identifier (e.g., “COCO 1.0”, “YOLO 1.1”)
filename: Output file path or name
include_images: Include image data (default: True)
pbar: Progress reporter for tracking download status
status_check_period: Seconds between status checks
location: Export location (LOCAL or CLOUD_STORAGE)
cloud_storage_id: Cloud storage ID if using cloud location

Import Annotations

Importing allows you to load existing annotations into CVAT tasks, useful for pre-annotation, transfer learning, or combining datasets.

Import via Web UI

Open your task
Click the Actions menu
Select Upload annotations
Choose the annotation format
Select your annotation file
Click OK to upload

CVAT will validate and import the annotations. You’ll see a notification when the import completes.

Import via CLI

Use the import-dataset command to upload annotations:

# Import COCO annotations
cvat-cli --auth user:password task import-dataset \
  --format "COCO 1.0" \
  --input annotations.json \
  123

# Import YOLO annotations from ZIP
cvat-cli task import-dataset \
  --format "YOLO 1.1" \
  --input yolo_labels.zip \
  456

# Import Pascal VOC annotations
cvat-cli task import-dataset \
  --format "PASCAL VOC 1.1" \
  --input voc_annotations.zip \
  789

Import options:

--format: Annotation format matching your input file
--input: Path to annotation file (JSON or ZIP)

Import via SDK

Programmatically import annotations using the SDK:

import cvat_sdk

# Connect to server
with cvat_sdk.make_client(
    host="https://app.cvat.ai",
    credentials=("username", "password")
) as client:
    # Get task
    task = client.tasks.retrieve(123)
    
    # Import COCO annotations
    task.import_annotations(
        format_name="COCO 1.0",
        filename="annotations.json"
    )
    
    print("Annotations imported successfully!")

Advanced import examples:

# Import with progress tracking
from cvat_sdk.core.progress import SimpleProgressReporter

pbar = SimpleProgressReporter()
task.import_annotations(
    format_name="YOLO 1.1",
    filename="yolo_labels.zip",
    pbar=pbar
)

# Import with mask-to-polygon conversion
task.import_annotations(
    format_name="COCO 1.0",
    filename="coco_with_masks.json",
    conv_mask_to_poly=True
)

# Batch import across multiple tasks
tasks = [client.tasks.retrieve(id) for id in [123, 456, 789]]

for task in tasks:
    annotation_file = f"task_{task.id}_annotations.json"
    task.import_annotations(
        format_name="COCO 1.0",
        filename=annotation_file
    )
    print(f"Imported annotations for task {task.id}")

Import parameters:

format_name: Annotation format identifier
filename: Path to annotation file
conv_mask_to_poly: Convert masks to polygons (default: None)
status_check_period: Seconds between status checks
pbar: Progress reporter

Format Requirements

Each format has specific requirements for successful import:

File Structure

JSON formats (COCO, Labelme): Single JSON file or ZIP with JSON
Text formats (YOLO): ZIP archive with .txt files and data.yaml
XML formats (Pascal VOC): ZIP with annotations/ and images/ directories

Label Matching

When importing annotations:

Labels must exist in the task before import
Label names must match exactly (case-sensitive)
Missing labels will cause import to fail

Create labels first via:

Web UI: Task settings → Labels
CLI: --labels parameter when creating task
SDK: Include labels in task specification

Image Matching

CVAT matches imported annotations to images by filename:

Annotations reference images by filename
CVAT matches these to uploaded task images
Unmatched images are skipped with warnings

Common Issues

Export Issues

Export fails or times out:

Large datasets may take time; check background jobs
Increase status_check_period for large exports
Check server logs for specific errors

Missing annotations in export:

Verify annotations are saved in the task
Check if format supports your annotation types
Some formats have limitations (see format conversion)

Import Issues

“Label not found” errors:

Create all required labels before import
Check label names match exactly
Use soft_attribute_import for dynamic attribute creation

“Image not found” warnings:

Ensure annotation filenames match uploaded images
Check file extensions and paths
Verify images were uploaded successfully

Format detection fails:

Verify file structure matches format requirements
Check JSON syntax for format-specific fields
Ensure ZIP archives have correct directory structure

Best Practices

Test with small datasets first before bulk operations
Backup before importing to avoid overwriting existing work
Verify labels match between source and destination
Use appropriate formats for your annotation types
Check format compatibility with your ML framework
Monitor background jobs for large import/export operations
Use version control for annotation files

Next Steps

Supported Formats - Complete list of available formats
Format Conversion - Converting between formats
CLI Reference - Full CLI command documentation
SDK Reference - Complete SDK API documentation

Get Started

Annotation

Projects & Tasks

Dataset Management

Integrations

Account & Organization

Import & Export Datasets

Export Datasets

Export via Web UI

Export via CLI

Export via SDK

Import Annotations

Import via Web UI

Import via CLI

Import via SDK

Format Requirements

File Structure

Label Matching

Image Matching

Common Issues

Export Issues

Import Issues

Best Practices

Next Steps

Build docs developers (and LLMs) love

Get Started

Annotation

Projects & Tasks

Dataset Management

Integrations

Account & Organization

Documentation Index

​Export Datasets

​Export via Web UI

​Export via CLI

​Export via SDK

​Import Annotations

​Import via Web UI

​Import via CLI

​Import via SDK

​Format Requirements

​File Structure

​Label Matching

​Image Matching

​Common Issues

​Export Issues

​Import Issues

​Best Practices

​Next Steps

Build docs developers (and LLMs) love

Export Datasets

Export via Web UI

Export via CLI

Export via SDK

Import Annotations

Import via Web UI

Import via CLI

Import via SDK

Format Requirements

File Structure

Label Matching

Image Matching

Common Issues

Export Issues

Import Issues

Best Practices

Next Steps