yoloutils 操作手册yoloutils是一组面向 YOLO 数据集的命令行工具用于标签统计、标签筛选、索引替换、数据集整理、图片裁剪、分类数据拆分和模型批量测试。作者: Neo netkillermsn.com官网: https://www.netkiller.cn1. 工具概览当前源码中的子命令如下子命令作用label查看classes.txt、统计标签数量、搜索标签所在文件merge按文件名合并两组 YOLO 标注copy按标签名称复制标注文件和图片remove删除指定标签索引或标签名称change批量替换标签索引crop使用 YOLO 模型检测并裁剪图片labelimg将 labelimg 风格数据整理为 YOLO 训练目录resize按长边尺寸缩放图片classify处理分类数据集并划分train/test/valtest用模型批量推理并输出表格或 CSV查看总帮助yoloutils-h2. 安装与运行2.1 环境要求Python 3.13依赖项pillowopencv-pythonpyyamltqdmtexttableultralytics2.2 从 PyPI 安装pipinstallnetkiller-yoloutils2.3 从源码安装gitclone https://github.com/netkiller/yoloutils.gitcdyoloutils pipinstall-e.2.4 构建 wheel 安装pipinstallbuild python-mbuild pipinstalldist/netkiller_yoloutils-*.whl --force-reinstall2.5 查看某个子命令帮助yoloutils label-hyoloutils classify-hyoloutilstest-h3. 数据准备3.1 YOLO 检测数据目录大多数命令面向 YOLO 检测标注目录通常如下dataset/ ├── classes.txt ├── image001.jpg ├── image001.txt ├── image002.jpg ├── image002.txt └── subdir/ ├── image101.jpg └── image101.txt说明classes.txt为类别清单每行一个类别名称。标注文件为 YOLO 标准格式class x_center y_center width height。当前源码中大多数流程按.jpg .txt成对处理png支持并不完整实际使用时建议统一为.jpg。多个命令会递归扫描source目录下的所有标注文件。3.2 分类数据目录classify命令要求按类别分目录source/ ├── cat/ │ ├── 001.jpg │ └── 002.jpg ├── dog/ │ ├── 101.jpg │ └── 102.jpg └── bird/ └── 201.jpg3.3 日志文件程序运行后会在当前工作目录生成类似下面的日志文件yoloutils.2026-04-07.log4. 命令详解4.1label用于查看classes.txt、统计标签数量以及检索包含某些标签的标注文件。命令格式yoloutils label--sourceDATASET[--classes|--total|--index|--search012]帮助信息usage: yoloutils.py label[-h][--source /tmp/dir1][--classes][--total][--index][--search123[123...]]options: -h,--helpshow thishelpmessage andexit--source/tmp/dir1 目录--classes查看 classes.txt 文件--total统计标签图数量--index统计标签索引数量--search123[123...]搜索标签常用示例# 查看 classes.txtyoloutils label--source./dataset--classes# 统计各标签出现次数yoloutils label--source./dataset--total# 仅按索引统计yoloutils label--source./dataset--index# 查找包含索引 0 和 2 的标注文件yoloutils label--source./dataset--search02实现说明--classes读取source/classes.txt并以表格输出。--total统计的是标注框数量不是图片数量。--index与--total使用同一套统计逻辑只是不再映射成标签名称。--search返回包含指定索引的标注文件路径列表。4.2merge将左侧目录中的标注文件与右侧目录中同名标注合并到输出目录同时复制左侧目录中的图片。命令格式yoloutils merge\--left./left\--right./right\--output./merged\--clean帮助信息usage: yoloutils.py merge[-h][--left /tmp/dir1][--right /tmp/dir2][--output /tmp/output][--clean]options: -h,--helpshow thishelpmessage andexit--left/tmp/dir1 左侧目录--right/tmp/dir2 右侧目录--output/tmp/output 最终输出目录--clean清理之前的数据使用前提左右目录中都使用 YOLO.txt标注文件。图片从--left目录复制到输出目录。当前实现默认图片扩展名为.jpg。右侧文件名匹配规则较特殊左侧若为name_0.txt右侧会查找name.txt。适用场景示例left/ ├── sample_0.jpg └── sample_0.txt right/ └── sample.txt合并后merged/ ├── sample_0.jpg └── sample_0.txt实现说明如果右侧缺少对应标注则仅复制左侧标注。如果右侧存在对应标注则把两个文本内容直接拼接写入输出文件。当前源码已修正顶层 CLI 的merge分发命令可以正常进入合并逻辑。4.3copy按标签名称筛选标注文件并复制对应的标注和图片到目标目录。命令格式yoloutils copy\--source./dataset\--target./picked\--labelperson,dog\--uuid\--clean帮助信息usage: yoloutils.py copy[-h][--source SOURCE][--target TARGET][--label LABEL][-u][-c]options: -h,--helpshow thishelpmessage andexit--sourceSOURCE 图片来源地址--targetTARGET 图片目标地址--labelLABEL 逗号分割多个标签 -u,--uuidUUID 文件名 -c,--clean清理目标文件夹常用示例# 复制含有 cat 标签的样本yoloutils copy--source./dataset--target./picked--labelcat# 复制多个标签yoloutils copy--source./dataset--target./picked--labelperson,car,bicycle# 输出文件名改为 UUIDyoloutils copy--source./dataset--target./picked--labeldog--uuid实现说明复制前会读取source/classes.txt把标签名称转换为索引。--label采用逗号分隔如person,dog,car。会把classes.txt一并复制到目标目录。当前实现主要按.jpg配对复制图片。该命令的复制逻辑依赖文件名和目录状态建议先在小样本目录验证输出结果。4.4remove从 YOLO 标注文件中删除指定标签。可以按索引删除也可以按标签名称删除。命令格式yoloutils remove\--source./dataset\--target./cleaned\--classes035\--clean或yoloutils remove\--source./dataset\--labelcatdog帮助信息usage: yoloutils.py remove[-h][--source SOURCE][--target TARGET][--clean][--classes123[123...]][--label label1 label2[label1 label2...]]options: -h,--helpshow thishelpmessage andexit--classes123[123...]标签序号--labellabel1 label2[label1 label2...]标签名称 通用参数:--sourceSOURCE 图片来源地址--targetTARGET 图片目标地址--clean清理之前的数据实现说明--classes接收标签索引列表。--label先读取source/classes.txt再转换成索引列表。如果指定了--target会把结果写入目标目录如果不指定则直接原地修改源文件。某个标注文件在删除后若没有任何标注行程序会删除对应的.txt和同名.jpg。当前实现写入--target时只保留文件名不保留原始子目录结构若不同子目录存在同名文件可能发生覆盖。常用示例# 删除索引 0 和 1yoloutils remove--source./dataset--target./cleaned--classes01# 删除标签名称 cat、dogyoloutils remove--source./dataset--target./cleaned--labelcatdog# 直接原地删除yoloutils remove--source./dataset--classes74.5change批量修改标签索引直接原地覆盖源标注文件。命令格式yoloutils change\--source./dataset\--search012\--replace345帮助信息usage: yoloutils.py change[-h][--source /tmp/dir1][--search123[123...]][--replace456[456...]]options: -h,--helpshow thishelpmessage andexit--source/tmp/dir1 目录--search123[123...]标签序号--replace456[456...]标签名称实现说明--search与--replace按位置一一对应。会递归处理source下所有.txt跳过classes.txt。该命令没有--target输出目录修改直接写回原文件。常用示例# 把 0 - 5, 1 - 6yoloutils change--source./dataset--search01--replace564.6crop使用 YOLO 模型批量检测图片并把检测区域裁剪到目标目录。命令格式yoloutils crop\--source./images\--target./cropped\--model./best.pt\--output./predict\--clean帮助信息usage: yoloutils.py crop[-h][--source SOURCE][--target TARGET][--clean][--model best.pt][--output /tmp/output]options: -h,--helpshow thishelpmessage andexit--modelbest.pt 模型--output/tmp/output Yolo 输出目录 通用参数:--sourceSOURCE 图片来源地址--targetTARGET 图片目标地址--clean清理之前的数据实现说明递归扫描source下的.jpg文件。--target保留原始相对目录结构。--model必填使用ultralytics.YOLO加载模型。--output存在时会额外保存带检测框的推理结果以及ultralytics生成的裁剪结果到output/crop/。当前实现每张图在target目录中只保留首个检测结果输出目标文件名沿用原图相对路径。常用示例yoloutils crop--source./images--target./cropped--model./best.pt4.7labelimg把 labelimg 风格的数据整理成 YOLO 训练目录结构并生成data.yaml。命令格式yoloutils labelimg\--source./labelimg_data\--target./yolo_data\--val10\--uuid\--clean帮助信息usage: yoloutils.py labelimg[-h][--source SOURCE][--target TARGET][--clean][--classes CLASSES][--val10][--uuid][--check]options: -h,--helpshow thishelpmessage andexit--classesCLASSES classes.txt 文件--val10检验数量--uuid输出文件名使用UUID--check图片检查 corrupt JPEG restored and saved 通用参数:--sourceSOURCE 图片来源地址--targetTARGET 图片目标地址--clean清理之前的数据输出目录结构yolo_data/ ├── train/ │ ├── images/ │ └── labels/ ├── val/ │ ├── images/ │ └── labels/ ├── test/ │ ├── images/ │ └── labels/ └── data.yaml实现说明程序实际读取的是source/classes.txt。--val表示每个标签随机抽取多少个样本进入val不是百分比。所有样本会先进入train再从中抽样复制到val。test目录会创建但当前实现不会自动填充测试集。--uuid会把输出的图片和标签文件名改为 UUID。当前源码中声明了--classes和--check参数但这两个参数在实现里尚未真正生效。图片配对逻辑主要按同名.jpg处理准备数据时建议统一使用.jpg。常用示例# 基本整理yoloutils labelimg--source./labelimg_data--target./yolo_data# 每个标签抽取 20 个样本到验证集yoloutils labelimg--source./labelimg_data--target./yolo_data--val20# 生成 UUID 文件名yoloutils labelimg--source./labelimg_data--target./yolo_data--uuid4.8resize按长边尺寸缩放图片小于目标尺寸的图片会直接复制。命令格式yoloutils resize\--source./images\--target./resized\--imgsz640\--clean帮助信息usage: yoloutils.py resize[-h][--source SOURCE][--target TARGET][--clean][--imgsz640][--output]options: -h,--helpshow thishelpmessage andexit--imgsz640长边尺寸--output输出识别图像 通用参数:--sourceSOURCE 图片来源地址--targetTARGET 图片目标地址--clean清理之前的数据实现说明递归扫描source下的.jpg文件。输出目录保留原始相对路径。长边大于--imgsz时才会缩放否则直接复制原图。输出统计表中的“未处理”表示未缩放、直接复制的文件数。当前源码声明了--output参数但实际流程中没有使用该目录。常用示例yoloutils resize--source./images--target./resized--imgsz640yoloutils resize--source./images--target./resized--imgsz19204.9classify处理分类数据集并自动生成train/test/val目录结构。支持在复制训练集之前先用检测模型裁剪图片。命令格式yoloutils classify\--source./source\--target./dataset\--test100\--crop\--model./best.pt\--output./predict\--checklist./checklist\--uuid\--verbose\--clean帮助信息usage: yoloutils.py classify[-h][--source SOURCE][--target TARGET][--clean][--output][--checklist][--test100][--crop][--model][--uuid][--verbose]options: -h,--helpshow thishelpmessage andexit--output输出识别图像--checklist输出识别图像--test100测试数量--crop裁剪--model裁剪模型--uuid重命名图片为UUID--verbose过程输出 通用参数:--sourceSOURCE 图片来源地址--targetTARGET 图片目标地址--clean清理之前的数据输出目录结构dataset/ ├── train/ │ ├── class_a/ │ └── class_b/ ├── test/ │ ├── class_a/ │ └── class_b/ └── val/ ├── class_a/ └── class_b/实现说明首先把所有源图片复制或裁剪到train。然后从train中随机抽样复制到test和val。--test表示每个类别抽样多少张同时用于test和val两个集合。--crop生效时必须同时提供有效的--model。裁剪模式下若一张图检测出多个框会输出多个_0、_1之类的裁剪文件。--output用于保存带检测框的推理结果。--checklist用于保存多框样本的检查结果和裁剪产物便于人工复核。--uuid会将目标文件改名为 UUID。常用示例# 不裁剪直接划分分类数据集yoloutils classify--source./source--target./dataset# 每个类别抽样 50 张到 test 和 valyoloutils classify--source./source--target./dataset--test50# 先检测裁剪再做分类数据集yoloutils classify\--source./source\--target./dataset\--crop\--model./best.pt\--output./predict\--checklist./checklist4.10test用 YOLO 模型批量推理目录中的图片并输出表格结果可选保存 CSV 和可视化图片。命令格式yoloutilstest\--source./images\--model./best.pt\--csv./result.csv\--output./predict帮助信息usage: yoloutils.pytest[-h][--source SOURCE][--target TARGET][--clean][--model MODEL][--csv result.csv][--output OUTPUT]options: -h,--helpshow thishelpmessage andexit--modelMODEL 模型路径--csvresult.csv 保存测试结果--outputOUTPUT 测试结果输出路径 通用参数:--sourceSOURCE 图片来源地址--targetTARGET 图片目标地址--clean清理之前的数据实现说明会递归扫描source下除.txt和.DS_Store之外的文件。每张图只记录首个检测结果的标签和置信度。推理完成后会输出表格并计算总数、未检出数量和平均置信度。--csv会把结果保存为 CSV。--output会保存带检测框的结果图片。该命令虽然继承了通用参数中的--target、--clean但当前实现没有使用它们。常用示例# 批量测试并保存 CSVyoloutilstest--source./images--model./best.pt--csv./result.csv# 同时保存可视化结果yoloutilstest--source./images--model./best.pt--output./predict5. 通用参数部分子命令复用以下参数参数说明--source输入目录--target输出目录--clean运行前先删除目标目录中的旧数据说明label和change不使用--target。test虽然带有--target、--clean帮助项但当前实现未使用。6. 使用建议批量操作前先备份原始数据尤其是change和未指定--target的remove。尽量统一使用.jpg图片避免因为扩展名处理差异导致图片未被复制。使用--clean时确认目标目录没有需要保留的旧文件。labelimg、classify、test涉及随机抽样或推理建议先在小目录上试跑一轮。若目录层级较深优先保证文件名唯一避免某些命令在输出时因只保留 basename 发生覆盖。7. 常见问题Q1: 提示classes.txt 文件不存在确认以下几点source目录下存在classes.txt文件名大小写正确运行目录和传入路径没有写错Q2: 标签统计结果和图片数对不上label --total统计的是标注框数量不是图片数量。一张图中如果有多个框会被累计多次。Q3: 为什么labelimg没有生成test数据当前实现只会创建test目录不会自动填充测试样本。Q4: 为什么某些图片没有被处理优先检查图片是否为.jpg标注文件和图片是否同名模型文件路径是否正确输出目录是否被旧数据覆盖8. 许可证MIT License