Ultralytics YOLO 命令行界面（CLI）完全指南：从训练到导出的 yolo TASK MODE ARGS 实战手册

导读

Ultralytics YOLO 的命令行界面（CLI）让开发者无需编写任何 Python 代码、也无需创建自定义脚本，即可在终端中直接完成目标检测、实例分割、语义分割、深度估计、图像分类、姿态估计与旋转框检测等全流程任务。本文基于当前仓库 ultralytics（版本 8.4.138，默认 YOLO26 系列模型）的官方 CLI 文档与源码，系统讲解 yolo TASK MODE ARGS 的语法规则、六大模式与七大任务、特殊命令、solutions 预置解决方案以及参数覆盖机制，读完即可在真实项目中直接复用文中命令。

---

一、认识 yolo 命令入口

CLI 的底层入口定义在 pyproject.toml 中，通过 Python 打包机制把控制台脚本注册到系统环境：

[project.scripts]
yolo = "ultralytics.cfg:entrypoint"
ultralytics = "ultralytics.cfg:entrypoint"

也就是说，安装该包后，终端中同时存在 yolo 与 ultralytics 两个等价命令，二者都指向 ultralytics/cfg/init.py 中定义的 entrypoint() 函数。安装方式为常规 pip 安装（例如 pip install ultralytics），当前仓库 __version__ 在 ultralytics/init.py 中记录为 8.4.138，可通过 yolo version 随时核对环境版本。

CLI 的核心价值在于：所有模式（训练、验证、预测、导出、追踪、基准测试）的参数默认值都统一收敛在 ultralytics/cfg/default.yaml 这一份配置文件中，命令行只需用 arg=value 覆盖你关心的少数项，其余全部走默认值，学习成本极低。

---

二、命令语法：yolo TASK MODE ARGS

一切 yolo 命令遵循同一套语法：

yolo TASK MODE ARGS

三个部分的含义如下：

• TASK（可选）：detect、segment、semantic、depth、classify、pose、obb 之一。若未显式指定，YOLO 会根据模型文件类型自动推断（例如 yolo26n-seg.pt 会被识别为分割任务）。
• MODE（必填）：train、val、predict、export、track、benchmark 之一。
• ARGS（可选）：任意多个自定义 arg=value 键值对，例如 imgsz=320，用于覆盖默认配置。

TASK 与 MODE 的合法取值并非文档口头约定，而是直接以源码常量形式定义在 ultralytics/cfg/init.py：

MODES = ("train", "val", "predict", "export", "track", "benchmark")
TASKS = ("detect", "segment", "semantic", "depth", "classify", "pose", "obb")

同时源码为每个任务预置了默认数据集与默认模型（ultralytics/cfg/init.py）：例如检测任务缺省数据为 coco8.yaml、模型为 yolo26n.pt；姿态任务为 coco8-pose.yaml + yolo26n-pose.pt；旋转框任务为 dota8.yaml + yolo26n-obb.pt。这些默认值意味着即使命令里什么都不写全，CLI 也不会报错，而是打印一条 warning 后自动补全，非常适合新手快速上手。

快速上手五连击

1. Train —— 训练检测模型

yolo train data=coco8.yaml model=yolo26n.pt epochs=10 lr0=0.01

用 COCO8 迷你数据集训练 YOLO26n，10 个 epoch，初始学习率 0.01。

2. Predict —— 用预训练分割模型预测 YouTube 视频

yolo predict model=yolo26n-seg.pt source='https://youtu.be/LNwODJXcvt4' imgsz=320

source 可接受本地文件、目录、URL、视频流乃至 YouTube 链接，imgsz=320 覆盖默认 640 输入尺寸。

3. Val —— 验证预训练模型

yolo val model=yolo26n.pt data=coco8.yaml batch=1 imgsz=640

batch size 1、输入尺寸 640，输出 mAP/precision/recall 等指标。

4. Export —— 导出分类模型到 ONNX

yolo export model=yolo26n-cls.pt format=onnx imgsz=224,128

导出无需写 TASK，因为任务由模型文件自动推断；这里还用 224,128 指定了非方形输入尺寸（高×宽）。

5. Special —— 特殊命令

yolo help
yolo checks
yolo version
yolo settings
yolo login API_KEY
yolo logout
yolo copy-cfg
yolo cfg

分别用于查看帮助、环境自检、查看版本、管理配置、登录账号（login/logout）、复制默认配置、预览全局配置。

⚠️ 参数书写规范（最容易踩的坑）

参数必须以 arg=val 形式传递：等号 = 连接键值，不同参数对之间用空格分隔。严禁使用 -- 参数前缀，也严禁在参数之间使用逗号：

yolo predict model=yolo26n.pt imgsz=640 conf=0.25        # ✅ 正确
yolo predict model yolo26n.pt imgsz 640 conf 0.25        # ❌ 缺少等号
yolo predict --model yolo26n.pt --imgsz 640 --conf 0.25  # ❌ 不能加 -- 前缀

这一规则在 entrypoint 源码 中有更精细的容错实现：即使误加了 -- 前缀或末尾多余逗号，CLI 也只会打印 warning 并自动纠正；但若一个合法参数缺少 = 号（如 yolo ... imgsz），会直接抛出带完整帮助信息的 SyntaxError，提示应写为 imgsz=640。真正未知的参数名则通过 check_dict_alignment() 校验并报错，避免拼写错误被静默吞掉。

---

三、Train：训练模式

在 COCO8 上以 100 个 epoch、输入尺寸 640 训练检测模型：

yolo detect train data=coco8.yaml model=yolo26n.pt epochs=100 imgsz=640

断点续训 Resume

训练意外中断后无需从头开始：

yolo detect train resume model=last.pt

resume 会读取上次训练保存的 last.pt 中的权重、data、超参数等全部状态继续训练。从源码看，entrypoint() 在处理 mode in {"train", "val"} 时，若存在 resume 参数就不会强行补充 data，这正是"续训不需要重新指定数据集"的底层原因。

值得关注的关键训练参数（默认值均见 ultralytics/cfg/default.yaml）：

参数	默认值	说明
epochs	100	训练轮数；若设置 time（小时数），将覆盖 epochs
patience	100	验证指标连续 N 轮无提升则早停
batch	16	批大小；传 0.0–1.0 浮点数启用 AutoBatch 按显存比例自动选
imgsz	640	训练/验证为方形整数；预测/导出可传 [h,w]
optimizer	auto	SGD、MuSGD、Adam、Adamax、AdamW、NAdam、RAdam、RMSProp 或 auto
device	—	0/[0,1]（CUDA）、cpu/mps、npu:0（昇腾）、xpu:0（Intel）
cos_lr	False	是否启用余弦学习率调度
amp	True	训练精度：True/fp16/bf16/False(fp32)
freeze	—	冻结前 N 层、指定层索引或模块名（如 "23.cv2"）做迁移学习
single_cls	False	是否把所有类别视为单类
rect	False	是否启用矩形批训练

此外，数据集配置文件统一存放在 ultralytics/cfg/datasets/，除 COCO 系外还覆盖 VOC、Objects365、DOTA、ADE20K、xView、VisDrone、各类 pose/segment/depth 数据集等数十个 YAML，参数 data= 直接引用即可。

---

四、Val：验证模式

验证已训练模型的精度。因为训练好的模型会把 data、imgsz 等参数作为模型属性一并保存，所以验证时通常无需再写参数：

# 官方预训练模型
yolo detect val model=yolo26n.pt

# 自定义训练得到的模型
yolo detect val model=path/to/best.pt

若需要以指定批大小与输入尺寸验证：

yolo detect val model=yolo26n.pt data=coco8.yaml batch=1 imgsz=640

验证输出包含 mAP50-95、mAP50、precision、recall 等指标。任务对应的核心指标由 TASK2METRIC 映射定义：检测与旋转框为 metrics/mAP50-95(B)，分割为 (M)，姿态为 (P)，语义分割为 mIoU，深度估计为 delta1，分类为 accuracy_top1。默认 split=val，可通过 split=test 或 split=train 切换评估数据切分。

---

五、Predict：预测模式

用训练好的模型对图片执行推理：

# 官方模型
yolo detect predict model=yolo26n.pt source='https://ultralytics.com/images/bus.jpg'

# 自定义模型
yolo detect predict model=path/to/best.pt source='https://ultralytics.com/images/bus.jpg'

source 支持文件、目录、URL、网络流、摄像头设备号（如 0）与 YouTube 链接。若不提供 source，CLI 会自动补默认素材（源码中 OBB 任务回退到 boats.jpg，其余任务回退到仓库 ASSETS 目录并给出 warning）。常用推理参数还包括：

参数	默认值	说明
conf	0.25	置信度阈值（val 默认 0.001）
iou	0.7	NMS 的 IoU 阈值
max_det	300	每张图最大检测数
classes	—	类别过滤，如 0 或 [0,2,3]
show	False	弹窗实时显示结果（支持窗口时）
save	True	保存预测结果
save_txt	False	以 txt（xywh 格式）保存结果
save_crop	False	保存每个检测目标的裁剪图
vid_stride	1	视频每隔 N 帧读一帧
agnostic_nms	False	是否使用类别无关 NMS

---

六、Export：导出模式

导出模型到 ONNX、CoreML 等不同推理格式：

yolo export model=yolo26n.pt format=onnx
yolo export model=path/to/best.pt format=onnx

导出无需指定 TASK（从模型自动推断）。若省略 format，源码默认导出 TorchScript（见 ultralytics/cfg/init.py）。

完整导出格式表如下（format 参数取值、产物命名与可用扩展参数，整理自 导出格式宏，model_name 为导出源模型名）：

格式	format 参数	产物	常用参数
PyTorch	—	yolo26n.pt	—
TorchScript	torchscript	.torchscript	imgsz, quantize, dynamic, nms, batch, device
ONNX	onnx	.onnx	imgsz, quantize, dynamic, simplify, opset, nms, batch, device
OpenVINO	openvino	_openvino_model/	imgsz, quantize, dynamic, nms, batch, device
TensorRT	engine	.engine	imgsz, quantize, dynamic, workspace, nms, batch, device
CoreML	coreml	.mlpackage	imgsz, dynamic, quantize, nms, batch, device
TF SavedModel	saved_model	_saved_model/	imgsz, keras, quantize, opset, nms, batch, device
TF GraphDef	pb	.pb	imgsz, opset, batch, device
TF Edge TPU	edgetpu	_edgetpu.tflite	imgsz, quantize, opset, batch, device
PaddlePaddle	paddle	_paddle_model/	imgsz, batch, device
MNN	mnn	.mnn	imgsz, batch, dynamic, quantize, nms, device
NCNN	ncnn	_ncnn_model/	imgsz, quantize, batch, device
IMX500	imx	_imx_model/	目前仅支持 YOLOv8n/YOLO11n 系列
RKNN	rknn	_rknn_model/	imgsz, batch, name, quantize, simplify, opset, device
ExecuTorch	executorch	_executorch_model/	imgsz, batch, device
Axelera	axelera	_axelera_model/	imgsz, batch, quantize, data, device
DEEPX	deepx	_deepx_model/	imgsz, quantize, simplify, opset, optimize, device
Qualcomm QNN	qnn	_qnn.onnx	imgsz, batch, name, quantize, simplify, opset, device
LiteRT	litert	.tflite	imgsz, quantize, batch, device
Hailo	hailo	_hailo_model/	imgsz, name, quantize, conf, iou, simplify
Huawei Ascend	ascend	_ascend_model/	imgsz, batch, name, quantize, opset, nms
Apple Core AI	coreai	.aimodel	imgsz, batch, quantize

量化参数 quantize 除 8/16/32 整数写法外，还接受 int8、fp16、w8a8、w16a16、w8a16（INT8 权重 + FP16 激活）等字符串别名，具体映射在 QUANTIZE_ALIASES 中定义。各格式的深度讲解请参阅 Export 模式文档 与 Integrations 目录下对应格式页面。

---

七、覆盖默认参数与默认配置文件

7.1 命令行直接覆盖

CLI 的核心理念是"默认合理、按需覆盖"，任何参数都能以 arg=value 形式在命令行尾部追加：

# 训练 10 个 epoch，学习率 0.01
yolo detect train data=coco8.yaml model=yolo26n.pt epochs=10 lr0=0.01

# 用预训练分割模型、320 输入尺寸预测 YouTube 视频
yolo segment predict model=yolo26n-seg.pt source='https://youtu.be/LNwODJXcvt4' imgsz=320

# 验证时批大小 1、输入尺寸 640
yolo detect val model=yolo26n.pt data=coco8.yaml batch=1 imgsz=640

7.2 整份替换默认配置 default.yaml

当参数过多、逐条书写不便时，可整体替换配置：

1. 先用特殊命令把默认配置复制到当前工作目录：

yolo copy-cfg

该命令在 copy_default_cfg() 中实现，把 ultralytics/cfg/default.yaml 复制为当前目录下的 default_copy.yaml 并打印使用提示。

2. 用 cfg= 参数指定新配置，同时仍可叠加其他参数：

yolo cfg=default_copy.yaml imgsz=320

从 entrypoint 源码 可以看到 cfg= 的特殊处理逻辑：检测到 k == "cfg" 后，会用 YAML.load() 加载你指定的 YAML 文件并把其中所有键值展开为 overrides（cfg 键本身除外），因此后续命令行参数与 YAML 内容会合并生效。

7.3 一个值得注意的语法糖

entrypoint() 支持为布尔参数省略 =True：由于布尔默认参数会被自动置为 True，直接写参数名即可激活，例如 yolo show 等价于 yolo show=True。

---

八、Solutions：开箱即用的 CV 解决方案命令

yolo solutions 把对象计数、裁剪、模糊、健身动作监测、热力图、实例分割、VisionEye、测速、排队管理、统计分析、Streamlit 实时推理与区域追踪等常见 CV 应用打包成一条条 CLI 命令，几乎所有参数默认即可运行。运行 yolo solutions help 可查看全部受支持方案及参数。

对象计数 Count

yolo solutions count show=True
yolo solutions count source="path/to/video.mp4" # 指定视频路径

目标裁剪 Crop

yolo solutions crop show=True
yolo solutions crop source="path/to/video.mp4" # 指定视频路径
yolo solutions crop classes="[0, 2]"           # 只裁剪指定类别

目标模糊 Blur

yolo solutions blur show=True
yolo solutions blur source="path/to/video.mp4" # 指定视频路径
yolo solutions blur classes="[0, 5]"           # 只模糊指定类别

健身动作监测 Workout

基于姿态模型监测锻炼动作，通过关键点三元组区分左右侧卷腹：

yolo solutions workout show=True
yolo solutions workout source="path/to/video.mp4" # 指定视频路径

yolo solutions workout kpts="[5, 11, 13]" # 左侧关键点
yolo solutions workout kpts="[6, 12, 14]" # 右侧关键点

热力图 Heatmap

展示目标密度与运动模式：

yolo solutions heatmap show=True
yolo solutions heatmap source="path/to/video.mp4"                                # 指定视频路径
yolo solutions heatmap colormap=cv2.COLORMAP_INFERNO                             # 自定义配色
yolo solutions heatmap region="[(20, 400), (1080, 400), (1080, 360), (20, 360)]" # 限定热力图区域

实例分割追踪 Isegment

yolo solutions isegment show=True
yolo solutions isegment source="path/to/video.mp4" # 指定视频路径
yolo solutions isegment classes="[0, 5]"           # 只分割指定类别

VisionEye

绘制目标指向观察者的视线：

yolo solutions visioneye show=True
yolo solutions visioneye source="path/to/video.mp4" # 指定视频路径
yolo solutions visioneye classes="[0, 5]"           # 只监控指定类别

车速估计 Speed

yolo solutions speed show=True
yolo solutions speed source="path/to/video.mp4" # 指定视频路径
yolo solutions speed meter_per_pixel=0.05       # 设置像素到真实世界的比例尺

排队计数 Queue

yolo solutions queue show=True
yolo solutions queue source="path/to/video.mp4"                                # 指定视频路径
yolo solutions queue region="[(20, 400), (1080, 400), (1080, 360), (20, 360)]" # 配置排队区域坐标

数据统计图 Analytics

依据追踪检测结果生成折线/柱状/面积/饼图：

yolo solutions analytics show=True
yolo solutions analytics source="path/to/video.mp4" # 指定视频路径
yolo solutions analytics analytics_type="pie" show=True
yolo solutions analytics analytics_type="bar" show=True
yolo solutions analytics analytics_type="area" show=True

Streamlit 网页推理 Inference

在浏览器中完成检测/分割/姿态估计：

yolo solutions inference
yolo solutions inference model="path/to/model.pt" # 使用自定义模型

区域内追踪 TrackZone

yolo solutions trackzone show=True
yolo solutions trackzone source="path/to/video.mp4"                                  # 指定视频路径
yolo solutions trackzone region="[(150, 150), (1130, 150), (1130, 570), (150, 570)]" # 配置区域坐标

区域计数 Region

yolo solutions region show=True
yolo solutions region source="path/to/video.mp4"                                # 指定视频路径
yolo solutions region region="[(20, 400), (1080, 400), (1080, 360), (20, 360)]" # 配置区域坐标

安防告警 Security

yolo solutions security show=True
yolo solutions security source="path/to/video.mp4" # 指定视频路径

停车场管理 Parking

需先通过 Python API（ParkingPtsSelection）生成车位标注 JSON：

yolo solutions parking source="path/to/video.mp4" json_file="bounding_boxes.json" # 需预生成 JSON
yolo solutions parking source="path/to/video.mp4" json_file="bounding_boxes.json" model="yolo26n.pt"

帮助 Help

yolo solutions help

所有解决方案的完整目录与参数说明见 Solutions 文档，对应实现类（ObjectCounter、Heatmap、SpeedEstimator、QueueManager、Analytics、TrackZone 等）位于 ultralytics/solutions/ 目录。

---

九、特殊命令详解

命令	作用
yolo help	打印完整 CLI 帮助（等同 yolo 语法说明，源自 CLI_HELP_MSG）
yolo checks	运行环境自检（依赖、版本、硬件可用性，对应 ultralytics.utils.checks）
yolo version	打印当前版本号
yolo settings	查看/修改本地 Ultralytics 设置
yolo login API_KEY	登录 Ultralytics 账号并保存凭据
yolo logout	登出
yolo copy-cfg	复制 default.yaml 为当前目录的 default_copy.yaml
yolo cfg	打印全局默认配置参数（对应 default.yaml 内容）

这些特殊命令在 entrypoint() 中以字典 special 方式分发注册，且源码做了人性化容错：自动补全单数形式（checks/check 均可）、并兼容 -help/--help 等带横杠写法（打印 warning 后自动去掉前缀执行）。仓库还内置了完整的 CLI 回归测试（见 tests/test_cli.py），覆盖上述模式的常用路径。

---

十、CLI 底层解析机制速览

理解 yolo 命令"宽容"背后的机制，有助于排查参数问题：

1. 参数预处理：merge_equals_args() 负责把 = 两侧意外被空格拆开的写法重新合并；
2. 键值解析：每个 arg=value 通过 parse_key_value_pair() 拆分为 (key, value)，再由 smart_value() 自动把字符串还原为数值、布尔、列表等类型（例如 classes="[0,2]" 会被解析为列表）；
3. 任务/模式识别：裸写的 token 若命中 TASKS 或 MODES 则被识别为 task/mode；注意源码对 task=track 会告警并自动改写为 task=detect, mode=track，因为追踪本质是检测 + 跟踪器；
4. 模型推断任务：若只给了 model 未给 task，会依据模型文件名中的 rtdetr、fastsam、sam、yoloe、world 等标识自动选择对应的 YOLO/RTDETR/FastSAM/SAM 类加载；
5. 默认值补全：缺 mode 用 predict，缺 model 用 yolo26n.pt，缺 source 用默认素材，缺 data 用任务默认数据集，缺 format 用 torchscript，全部补全后统一调用 getattr(model, mode)(**overrides) 执行；
6. 类型校验：CFG_FLOAT_KEYS 等常量集合在 check_cfg() 中对数值类参数做类型检查，传错类型会给出明确报错。

最终所有参数的默认值全集，均以"键 + 注释"的 YAML 形式维护在 ultralytics/cfg/default.yaml，该文件是查阅某个参数默认取值的第一权威来源。

---

十一、常见问题（FAQ）

Q1：如何用 CLI 训练模型？

终端执行一行命令即可，例如训练 10 个 epoch、学习率 0.01 的检测模型：

yolo train data=coco8.yaml model=yolo26n.pt epochs=10 lr0=0.01

参数全集见 配置指南（本地对应文件 docs/en/usage/cfg.md）。

Q2：CLI 支持哪些任务与操作？

支持检测、分割、语义分割、深度估计、分类、姿态估计、旋转框检测七大类任务，常用操作包括：

• 训练：yolo train data=<data.yaml> model=<model.pt> epochs=<num>
• 预测：yolo predict model=<model.pt> source=<数据源> imgsz=<尺寸>
• 导出：yolo export model=<model.pt> format=<导出格式>
• 解决方案：yolo solutions <solution_name>

任务详情可分别参考 检测、分割、语义分割、深度估计、分类、姿态估计、旋转框 文档。

Q3：如何用 CLI 验证模型精度？

使用 val 模式：

yolo val model=yolo26n.pt data=coco8.yaml batch=1 imgsz=640

输出 mAP、precision、recall 等评估指标（各任务核心指标见上文 TASK2METRIC 映射）。

Q4：CLI 支持导出哪些格式？

支持 ONNX、TensorRT、CoreML、TensorFlow 系、NCNN、MNN、LiteRT、QNN、Hailo、昇腾等多种格式：

yolo export model=yolo26n.pt format=onnx

完整格式表见本文第六节，各格式专用参数详见 Export 文档。

Q5：如何使用 CLI 中的预置解决方案？

例如对视频做对象计数：

yolo solutions count source="path/to/video.mp4"

这些方案几乎零配置即可运行；yolo solutions help 可列出全部方案及其可定制参数。

---

进一步阅读

• Configuration 配置指南：全部参数的默认值、类型与逐项说明
• Train 训练模式、Val 验证模式、Predict 预测模式、Export 导出模式、Track 追踪模式、Benchmark 基准模式
• Solutions 解决方案目录
• Python 使用指南：同一套能力在 Python API 中的等价写法
• 源码入口：ultralytics/cfg/init.py、默认配置 ultralytics/cfg/default.yaml、CLI 测试 tests/test_cli.py