Skip to main content
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

  1. Navigate to your task or project
  2. Click the Actions menu (three dots)
  3. Select Export dataset
  4. Choose your desired format from the dropdown
  5. Toggle Save images if you want to include image data
  6. 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

  1. Open your task
  2. Click the Actions menu
  3. Select Upload annotations
  4. Choose the annotation format
  5. Select your annotation file
  6. 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:
  1. Labels must exist in the task before import
  2. Label names must match exactly (case-sensitive)
  3. 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

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

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us