命令行界面（CLI）

July 19, 2026 · View on GitHub

X-AnyLabeling 提供命令行界面，用于启动图形界面、查询系统信息和转换标签格式。

Note

使用命令行前，请先按照快速入门指南安装对应运行环境的依赖。

0. 目录

1. 图形界面启动选项

# 常规启动
xanylabeling

# 打开指定的图像文件
xanylabeling --filename /path/to/image.jpg

# 打开指定的图像文件夹
xanylabeling --filename /path/to/folder

# 设置输出目录
xanylabeling --output /path/to/output

# 使用自定义配置文件
xanylabeling --config /path/to/config.yaml

# 设置日志级别
xanylabeling --logger-level debug

# 禁用自动更新检查
xanylabeling --no-auto-update-check

# 将 Qt 图像分配上限提高到 1024 MB
xanylabeling --qt-image-allocation-limit 1024

2. 系统命令

2.1 显示帮助信息

  • 输入
xanylabeling --help
  • 输出
usage: xanylabeling [-h] [--reset-config] [--logger-level {debug,info,warning,fatal,error}] [--no-auto-update-check] [--qt-platform QT_PLATFORM]
                    [--qt-image-allocation-limit QT_IMAGE_ALLOCATION_LIMIT] [--filename [FILENAME]] [--output OUTPUT]
                    [--config CONFIG] [--nodata] [--autosave] [--nosortlabels] [--flags FLAGS] [--labelflags LABEL_FLAGS] [--labels LABELS] [--validatelabel {exact}] [--keep-prev]
                    {help,checks,version,config,convert} ...

positional arguments:
  {help,checks,version,config,convert}
                        available commands
    help                show help message
    checks              display system and package information
    version             show version information
    config              show config file path
    convert             run conversion tasks

options:
  -h, --help            show this help message and exit
  --reset-config        reset qt config
  --logger-level {debug,info,warning,fatal,error}
                        logger level
  --no-auto-update-check
                        disable automatic update check on startup
  --qt-platform QT_PLATFORM
                        Force Qt platform plugin (e.g., 'xcb', 'wayland'). If not specified, Qt will auto-detect the platform.
  --qt-image-allocation-limit QT_IMAGE_ALLOCATION_LIMIT
                        Override Qt image allocation limit in MB. Qt default is 256 MB. Use 0 to disable the limit.
  --filename [FILENAME]
                        image or label filename; If a directory path is passed in, the folder will be loaded automatically
  --output OUTPUT, -O OUTPUT, -o OUTPUT
                        output file or directory (if it ends with .json it is recognized as file, else as directory)
  --config CONFIG       config file or yaml-format string (default: /home/cvhub/.xanylabelingrc)
  --nodata              stop storing image data to JSON file
  --autosave            auto save
  --nosortlabels        stop sorting labels
  --flags FLAGS         comma separated list of flags OR file containing flags
  --labelflags LABEL_FLAGS
                        yaml string of label specific flags OR file containing json string of label specific flags (ex. {person-\d+: [male, tall], dog-\d+: [black, brown, white], .*:
                        [occluded]})
  --labels LABELS       comma separated list of labels OR file containing labels
  --validatelabel {exact}
                        label validation types
  --keep-prev           keep annotation of previous frame

2.2 显示系统和软件包信息

  • 输入
xanylabeling checks
  • 输出
Application
────────────────────────────────────────────────────────────
  App Name:          X-AnyLabeling
  App Version:       4.0.0
  Preferred Device:  CPU
────────────────────────────────────────────────────────────
System
────────────────────────────────────────────────────────────
  Operating System:  Linux-6.6.87.2-microsoft-standard-WSL2-x86_64-with-glibc2.31
  CPU:               x86_64
  CPU Count:         20
  RAM:               31.2 GB
  Disk:              841.6/1006.9 GB
  GPU:               CUDA:0 (NVIDIA GeForce RTX 3060, 12288MiB)
  CUDA:              V11.6.124
  Python Version:    3.12.10
────────────────────────────────────────────────────────────
Packages
────────────────────────────────────────────────────────────
  PyQt6 Version:                           6.9.1
  ONNX Version:                            1.19.1
  ONNX Runtime Version:                    1.23.2
  ONNX Runtime GPU Version:                None
  OpenCV Contrib Python Headless Version:  4.11.0.86
────────────────────────────────────────────────────────────

2.3 显示应用版本信息

  • 输入
xanylabeling version
  • 输出
4.0.0

2.4 显示配置文件路径

  • 输入
xanylabeling config
  • 输出
~/.xanylabelingrc

3. 标签格式转换命令

3.1 列出所有可用的转换任务

  • 输入
xanylabeling convert
  • 输出
================================================================================
SUPPORTED CONVERSION TASKS
================================================================================

📥 IMPORT TO XLABEL
--------------------------------------------------------------------------------
  • yolo2xlabel [detect, segment, obb, pose]
  • voc2xlabel [detect, segment]
  • coco2xlabel [detect, segment, pose]
  • dota2xlabel
  • mot2xlabel
  • ppocr2xlabel [rec, kie]
  • mask2xlabel
  • vlmr12xlabel
  • odvg2xlabel

📤 EXPORT FROM XLABEL
--------------------------------------------------------------------------------
  • xlabel2yolo [detect, segment, obb, pose]
  • xlabel2voc [detect, segment]
  • xlabel2coco [detect, segment, pose]
  • xlabel2dota
  • xlabel2mask
  • xlabel2mot
  • xlabel2mots
  • xlabel2odvg
  • xlabel2vlmr1
  • xlabel2ppocr [rec, kie]

================================================================================
Total: 19 conversion tasks
================================================================================

Usage:
  xanylabeling convert                          # Show all tasks
  xanylabeling convert --task <task>            # Show detailed help for a task
  xanylabeling convert --task <task> [options]  # Run conversion

3.2 显示特定任务的详细帮助

  • 输入（以 yolo2xlabel 为例）
xanylabeling convert --task yolo2xlabel
  • 输出
================================================================================
TASK: yolo2xlabel
================================================================================

Description:
  Convert YOLO format to XLABEL

Modes:
  detect, segment, obb, pose

Required Arguments:
  --images
  --labels
  --output

Mode-Specific Arguments:
  detect: --classes
  segment: --classes
  obb: --classes
  pose: --pose_cfg

Examples:
  # Detection
  xanylabeling convert --task yolo2xlabel --mode detect --images ./images --labels ./labels \
    --output ./output --classes classes.txt

  # Segmentation
  xanylabeling convert --task yolo2xlabel --mode segment --images ./images --labels ./labels \
    --output ./output --classes classes.txt

  # OBB (Oriented Bounding Box)
  xanylabeling convert --task yolo2xlabel --mode obb --images ./images --labels ./labels \
    --output ./output --classes classes.txt

  # Pose
  xanylabeling convert --task yolo2xlabel --mode pose --images ./images --labels ./labels \
    --output ./output --pose-cfg pose_config.yaml

================================================================================

3.3 运行特定的转换任务

  • 输入（以 yolo2xlabel:detect 为例）
xanylabeling convert --task yolo2xlabel --mode detect --images ./images --labels ./labels \
    --output ./output --classes classes.txt
  • 输出
Converting YOLO detect to XLABEL: 100%|█████████████████████████████████████| 128/128 [00:00<00:00, 2456.47it/s]
✓ Converted 128 files to XLABEL format: ./output

3.4 转换参数说明

参数说明是否必需
--task转换任务名称是
--images图像目录路径否
--labels标签目录路径否
--output输出目录路径是
--classes类别文件路径否
--pose-cfg姿态配置文件路径否
--mode转换模式（如：detect、segment、obb、pose）否
--mapping映射表文件路径否
--skip-empty-files跳过创建空输出文件（仅支持 xlabel2yolo 和 xlabel2voc）否

更多信息参见《用户手册》中的标签导入导出。

4. 常见问题

Q1：什么是 XLABEL 格式？

XLABEL 是 X-AnyLabeling 的原生 JSON 格式。它以人类可读的格式存储所有标注信息，包括对象信息、标签信息、属性信息及元数据等。

Q2：是否需要为所有转换提供类别名称？

以下任务必须提供类别名称：

  • YOLO 转换（detect、segment、obb 模式）
  • COCO 转换（detect、segment 模式）
  • MOT 转换

VOC 格式在 XML 文件中嵌入了类别名称，因此不需要单独的类别文件。

Q3：如何创建 classes.txt 文件？

只需创建一个文本文件，每行一个类别名称：

person
car
bicycle
dog
cat

行号（从 0 开始索引）对应类别 ID。

Q4：MOT 和 MOTS 有什么区别？

  • MOT：使用边界框的多目标跟踪
  • MOTS：使用分割掩码的多目标跟踪

Q5：可以直接在格式之间转换而不经过 XLABEL 吗？

暂不支持。所有转换都需要以 XLABEL 作为中间格式：

  1. 首先转换为 XLABEL
  2. 然后从 XLABEL 转换为目标格式

Q6：如果图像在子目录中怎么办？

转换器当前仅处理指定目录中的图像。对于嵌套目录，您可能需要多次运行转换或展平目录结构。

Q7：如何在 Windows 上处理非 ASCII 路径？

转换器内置了对非 ASCII 路径的支持。确保您的终端编码设置为 UTF-8：

chcp 65001  # 在 Windows CMD 中

Q8：--skip-empty-files 选项是什么？

此选项（由 xlabel2yolo 和 xlabel2voc 支持）可防止为没有标注的图像创建空标签文件。当您想区分"未标注"和"已标注但为空"的图像时，这很有用。

Q9：可以使用相对路径吗？

是的，支持相对路径和绝对路径。相对路径从当前工作目录解析。

Q10：如何转换单个文件？

将单个文件放在目录中，然后对该目录运行转换。转换器会处理指定目录中的所有匹配文件。