Skip to main content
The convert command transforms annotation datasets from one format to another using Panlabel’s intermediate representation (IR) as a conversion hub.

​
Usage

panlabel convert --from <FORMAT> --to <FORMAT> -i <INPUT> -o <OUTPUT> [OPTIONS]

​
Parameters

​
--from
string
required
Source format. Use auto for automatic detection.Supported values: auto, ir-json, coco, cvat, label-studio, tfod, yolo, vocAliases: coco-json, cvat-xml, label-studio-json, ls, tfod-csv, ultralytics, yolov8, yolov5, pascal-voc, voc-xml
​
--to
string
required
Target format.Supported values: ir-json, coco, cvat, label-studio, tfod, yolo, vocAliases: Same as --from (except auto is not available)
​
--input
path
required
Input path to the source dataset. Can be a file or directory depending on the format.Short form: -i
​
--output
path
required
Output path for the converted dataset.Short form: -o
​
--strict
flag
default:"false"
Treat validation warnings as errors. If enabled, conversion will fail if the input dataset has any warnings.
​
--no-validate
flag
default:"false"
Skip input validation entirely. Use this for faster conversions when you’re confident the input is valid.Warning: Skipping validation may result in unexpected output if the input has issues.
​
--allow-lossy
flag
default:"false"
Allow conversions that drop information (e.g., metadata, images without annotations).By default, Panlabel blocks lossy conversions and shows a report of what would be lost. Use this flag to proceed anyway.
​
--report
string
default:"text"
Output format for the conversion report.Options:
  • text - Human-readable report
  • json - Machine-readable JSON (prints only JSON to stdout)

​
Auto-Detection Behavior

When using --from auto, Panlabel detects the input format based on file extension and content:

​
Directory-based Detection

  • YOLO: Directory contains labels/ subdirectory with .txt files, or the path itself is named labels/
  • VOC: Directory contains Annotations/ with .xml files and JPEGImages/ subdirectory
  • CVAT: Directory contains annotations.xml at the root

​
File-based Detection

  • .csv files: Detected as tfod (TensorFlow Object Detection)
  • .xml files: Root element <annotations> indicates cvat format
  • .json files:
    • Array-root with Label Studio task structure → label-studio
    • Object-root with annotations[0].bbox as array → coco
    • Object-root with annotations[0].bbox as object → ir-json
If multiple format markers match (ambiguous), auto-detection fails. Use --from to specify the format explicitly.

​
Examples

​
Basic Conversion with Auto-Detection

panlabel convert --from auto --to coco -i /data/my_yolo -o out.json
Automatically detects the YOLO format from the directory structure and converts to COCO.

​
COCO to YOLO Conversion

panlabel convert -f coco -t yolo -i annotations.json -o ./yolo_output/

​
Strict Validation During Conversion

panlabel convert --from coco --to ir-json \
  -i input.json -o output.json \
  --strict
Fails if the input has any validation warnings.

​
Allow Lossy Conversion

panlabel convert -f coco -t tfod -i input.json -o output.csv --allow-lossy
Proceeds with the conversion even if some information (like metadata) will be lost.

​
Skip Validation for Speed

panlabel convert -f ir-json -t coco \
  -i large_dataset.json -o output.json \
  --no-validate
Skips validation to speed up conversion on large, trusted datasets.

​
JSON Report Output

panlabel convert -f coco -t yolo \
  -i input.json -o ./yolo_dir/ \
  --report json > report.json
Outputs a machine-readable JSON report for programmatic processing.

​
Convert Label Studio to CVAT

panlabel convert --from label-studio --to cvat \
  -i tasks.json -o annotations.xml

​
Conversion Report

After conversion, Panlabel prints a report showing:
  • Number of images, annotations, and categories converted
  • Any information that was lost or transformed
  • Lossiness warnings (if applicable)
  • Conversion issues or edge cases

​
Text Report Example

Converted input.json (coco) -> output.json (ir-json)

Conversion Report:
  ✓ Lossless conversion
  Images: 150
  Annotations: 1,234
  Categories: 8

​
Lossy Conversion Example

Conversion blocked: coco -> tfod is lossy

Would lose:
  - 15 images without annotations
  - Dataset-level metadata
  
Use --allow-lossy to proceed anyway.

​
Format-Specific Notes

  • YOLO is directory-based: output path should be a directory
  • Requires classes.txt and data.yaml for category information
  • Bounding boxes are stored in normalized coordinates (0-1)
  • VOC is directory-based with Annotations/ and JPEGImages/ subdirectories
  • Each image has a separate XML annotation file
  • Output path should be the parent directory containing both subdirectories
  • TFOD uses a single CSV file with all annotations
  • May lose information like metadata or segmentation masks
  • Images without annotations are dropped by default
  • Can be a single XML file or a directory export
  • Preserves annotation attributes and metadata
  • Supports both file and directory-based formats

​
Exit Codes

  • 0 - Conversion successful
  • 1 - Validation failed (with --strict or on errors)
  • 1 - Lossy conversion blocked (without --allow-lossy)
  • 1 - Format detection failed
  • 1 - I/O or parsing errors

​
See Also

Supported Formats

Learn about all supported annotation formats

Validate Command

Validate datasets before conversion

Sample Command

Sample and convert in one step

Build docs developers (and LLMs) love

Get started for freeTalk to us