YOLOv10 快速上手指南：安装、CLI 命令行与 Python 接口实战

本指南基于 YOLOv10 仓库的 快速入门文档，系统讲解在本地环境安装 Ultralytics 软件包的四种方式（pip、conda、Git 与 Docker），并通过命令行（CLI）与 Python 接口快速完成训练、验证、推理与模型导出。读完本文，你将掌握 yolo 命令的完整语法与常用实战示例，能够用 Python 以几行代码加载模型并运行任务，同时学会查看与修改 Ultralytics 全局设置，为后续的 训练、预测 等环节扫清环境障碍。

安装 Ultralytics

YOLOv10 仓库以 ultralytics Python 包为核心交付物，其元信息定义在 pyproject.toml：包名为 ultralytics，要求 python >= 3.8，并声明了 torch>=1.8.0、torchvision>=0.9.0、opencv-python>=4.6.0 等核心依赖。安装方式灵活，既可以直接使用包管理器，也可以克隆仓库源码或使用 Docker 容器运行。

Pip 安装（推荐）

对于大多数用户，通过 pip 安装稳定版是最简单的方式：

# 从 PyPI 安装 ultralytics 包
pip install ultralytics

# 已有安装时更新到最新版本
pip install -U ultralytics

如果你想使用最新的开发版本（例如包含尚未发布的新特性），可以直接从 GitHub 安装。@main 指定 main 分支，也可换成其他分支名（如 @my-branch），不写则默认使用 main 分支：

# 从 GitHub 源码安装 ultralytics 包
pip install git+https://github.com/ultralytics/ultralytics.git@main

提示：PyTorch 的安装要求随操作系统与 CUDA 版本而异，官方建议先参照 PyTorch 官网指引完成 PyTorch 安装，再安装 ultralytics。若对依赖版本有严格管控需求，可参考仓库根目录的 requirements.txt（如 torch==2.0.1、onnx==1.14.0、pycocotools==2.0.7 等锁定版本）。

Conda 安装

Conda 是 pip 之外的另一种包管理器选择，适用于偏好 conda 环境的用户：

# 使用 conda 安装 ultralytics 包
conda install -c conda-forge ultralytics

CUDA 环境注意事项：在 CUDA 环境中，最佳实践是将 ultralytics、pytorch 与 pytorch-cuda 放在同一条命令中安装，让 conda 包管理器自行解决版本冲突；若分开安装，则应最后安装 pytorch-cuda，使其覆盖 CPU 版 pytorch：

# 在 conda 中一次性安装全部相关包
conda install -c pytorch -c nvidia -c conda-forge pytorch torchvision pytorch-cuda=11.8 ultralytics

仓库同时提供了基于 Miniconda3 的 Conda Docker 镜像构建文件 Dockerfile-conda，可用以下命令拉取并运行：

# 设置镜像名变量
t=ultralytics/ultralytics:latest-conda

# 从 Docker Hub 拉取最新的 ultralytics 镜像
sudo docker pull $t

# 以 GPU 支持方式运行容器（使用全部 GPU）
sudo docker run -it --ipc=host --gpus all $t

# 指定部分 GPU 运行
sudo docker run -it --ipc=host --gpus '"device=2,3"' $t

Git clone 安装

如果你希望参与项目开发，或想直接实验最新的源码，可以克隆仓库并以可编辑模式安装：

# 克隆 ultralytics 仓库
git clone https://github.com/ultralytics/ultralytics.git

# 进入克隆目录
cd ultralytics

# 以可编辑模式安装包（便于实时修改代码，无需重新安装）
pip install -e .

克隆后目录结构即与当前仓库一致，核心代码位于 ultralytics/ 下，其中 模型入口 同时导出了 YOLO、YOLOv10、YOLOWorld、SAM、RTDETR 等模型类。对 YOLOv10 而言，其网络结构定义在 v10 模型配置文件（含 v10n/s/m/l/b/x 共 6 种规模），可通过 YOLOv10('yolov10n.yaml') 直接使用。

Docker 安装

Docker 可以在隔离容器中运行 ultralytics 包，避免本地安装的复杂性，同时获得验证过的稳定运行环境。当前仓库的 docker 目录提供多套 Dockerfile，覆盖不同平台与使用场景：

• Dockerfile：GPU 镜像，推荐用于训练；
• Dockerfile-arm64：针对 ARM64 架构优化，可用于树莓派等设备；
• Dockerfile-cpu：基于 Ubuntu 的 CPU-only 版本，适合无 GPU 环境下的推理；
• Dockerfile-jetson：针对 NVIDIA Jetson 设备定制，集成 GPU 支持；
• Dockerfile-python：仅含 Python 与必要依赖的精简镜像，适合轻量应用与开发；
• Dockerfile-conda：基于 Miniconda3，通过 conda 安装 ultralytics 包。

拉取并运行最新镜像：

# 设置镜像名变量
t=ultralytics/ultralytics:latest

# 拉取最新镜像
sudo docker pull $t

# 以 GPU 支持方式运行容器
sudo docker run -it --ipc=host --gpus all $t          # 全部 GPU
sudo docker run -it --ipc=host --gpus '"device=2,3"' $t  # 指定 GPU

参数说明：-it 分配伪终端并保持标准输入打开，便于与容器交互；--ipc=host 将进程间通信（IPC）命名空间设为宿主机，用于共享内存；--gpus all 使容器内可访问全部 GPU。如需在容器内访问宿主机文件，可通过 -v 挂载本地目录：

# 将本地目录挂载到容器内目录
sudo docker run -it --ipc=host --gpus all -v /path/on/host:/path/in/container $t

其中 /path/on/host 替换为宿主机目录路径，/path/in/container 替换为容器内的目标路径。

使用 CLI 命令行

Ultralytics 命令行接口（CLI）无需 Python 环境即可用单行命令完成所有任务。安装包后，yolo 命令由 pyproject.toml 中 <a href="https://link.gitcode.com/i/81539edd0068c8d8e5fa48367fbbec0a" target="_blank">project.scripts] 声明的入口 yolo = "ultralytics.cfg:entrypoint" 提供，其解析实现位于 [entrypoint 函数。

CLI 语法

yolo TASK MODE ARGS

• TASK（可选）为任务类型，包括 detect、segment、classify、pose（当前仓库还扩展支持 obb 旋转框任务）；
• MODE（必填）为运行模式，包括 train、val、predict、export、track；
• ARGS（可选）为 arg=value 形式的参数对，如 imgsz=640，用于覆盖默认配置。

全部 ARGS 可查看完整 配置指南，也可直接执行 yolo cfg 查看默认配置（该命令实际打印 default.yaml 的内容）。从源码看，entrypoint 会先构造 full_args_dict，将默认配置、任务、模式与特殊命令合并，再逐一解析命令行中的 key=value 对并合并为 overrides（ultralytics/cfg/init.py#L473-L495）。

常用命令示例

训练：使用 coco128 数据集训练检测模型 10 个 epoch，初始学习率 0.01：

yolo train data=coco128.yaml model=yolov8n.pt epochs=10 lr0=0.01

对 YOLOv10，可将 model 替换为 yolov10n.yaml（结构定义见 ultralytics/cfg/models/v10/yolov10n.yaml），数据配置则可使用仓库内置的 coco8.yaml 等小型数据集快速验证流程：

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

预测：使用预训练分割模型以图像尺寸 320 推理 YouTube 视频：

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

验证：以 batch-size 1、图像尺寸 640 评估预训练检测模型：

yolo val model=yolov8n.pt data=coco128.yaml batch=1 imgsz=640

导出：将 YOLOv8n 分类模型导出为 ONNX 格式，图像尺寸 224×128（无需指定 TASK）：

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

特殊命令：查看版本、设置、运行检查等：

yolo help       # 显示帮助信息
yolo checks     # 收集并显示系统环境信息
yolo version    # 显示当前包版本
yolo settings   # 查看全局设置
yolo copy-cfg   # 复制默认配置文件到当前目录
yolo cfg        # 打印默认配置

从 entrypoint 源码 可见，这些特殊命令在解析阶段被提前拦截执行：checks 调用系统信息收集、version 打印版本号、settings 调用设置管理器、cfg 打印默认配置。

参数格式注意事项

参数必须以 arg=val 形式传递，用等号 = 分隔、以空格区分参数对。不要使用 -- 参数前缀或逗号 , 分隔：

• yolo predict model=yolov8n.pt imgsz=640 conf=0.25 ✅ 正确
• yolo predict model yolov8n.pt imgsz 640 conf 0.25 ❌ 缺少 =
• yolo predict model=yolov8n.pt, imgsz=640, conf=0.25 ❌ 不能使用逗号
• yolo predict --model yolov8n.pt --imgsz 640 --conf 0.25 ❌ 不能使用 --

实际上源码对以上误用做了容错处理：entrypoint 会剥离多余的 -- 前缀与尾部逗号并给出警告（ultralytics/cfg/init.py#L481-L487），但遵循规范写法始终是最稳妥的方式。更多细节见 CLI 指南。

使用 Python 接口

YOLO 的 Python 接口面向需要在项目中嵌入检测、分割、分类能力的开发者，几行代码即可完成加载模型、训练、验证、推理与导出 ONNX：

from ultralytics import YOLO

# 从零创建新的 YOLO 模型
model = YOLO('yolov8n.yaml')

# 加载预训练 YOLO 模型（训练时推荐）
model = YOLO('yolov8n.pt')

# 使用 coco128 数据集训练 3 个 epoch
results = model.train(data='coco128.yaml', epochs=3)

# 在验证集上评估模型性能
results = model.val()

# 对图像执行目标检测
results = model('https://ultralytics.com/images/bus.jpg')

# 将模型导出为 ONNX 格式
success = model.export(format='onnx')

在当前仓库中，由于 ultralytics 包同时导出 YOLOv10 类（见 ultralytics/init.py），YOLOv10 用户可以这样起步：

from ultralytics import YOLOv10

# 从配置文件创建 YOLOv10 模型
model = YOLOv10('yolov10n.yaml')

# 使用内置示例图片（仓库自带 ultralytics/assets/bus.jpg）推理
results = model.predict(source='ultralytics/assets/bus.jpg')

model.train()、model.val()、model.predict() 等方法与 CLI 中对应模式共享同一套配置体系，所有参数均可作为关键字参数传入，且与 yolo 命令行中的 arg=value 一一对应。完整用法参见 Python 指南。

Ultralytics 设置管理

Ultralytics 提供了强大的设置管理系统，通过 ultralytics.utils 模块中的 SettingsManager 类实现（ultralytics/utils/init.py#L906）。设置保存在用户配置目录下的 YAML 文件（默认路径为 USER_CONFIG_DIR / 'settings.yaml'，其中 USER_CONFIG_DIR 可由环境变量 YOLO_CONFIG_DIR 覆盖），可通过 Python 或 CLI 查看与修改。

查看设置

Python 方式：导入 settings 对象查看全部设置或读取单个键：

from ultralytics import settings

# 查看全部设置
print(settings)

# 返回某一项设置
value = settings['runs_dir']

CLI 方式：

yolo settings

修改设置

Python 方式：调用 settings.update() 修改，调用 settings.reset() 恢复默认值：

from ultralytics import settings

# 修改单项设置
settings.update({'runs_dir': '/path/to/runs'})

# 一次修改多项设置
settings.update({'runs_dir': '/path/to/runs', 'tensorboard': False})

# 重置为默认值
settings.reset()

CLI 方式：

# 修改单项设置
yolo settings runs_dir='/path/to/runs'

# 一次修改多项设置
yolo settings runs_dir='/path/to/runs' tensorboard=False

# 重置为默认值
yolo settings reset

从 SettingsManager 实现 可以看到：初始化时会自动生成默认设置并写入 YAML；若检测到本地设置与默认设置的键、类型或版本不一致，会自动重置为默认值并给出警告；update() 在更新内存值的同时会立即 save() 到 YAML 文件，保证持久化；此外还会校验 datasets_dir 与 runs_dir 不能相同，避免训练时的潜在冲突。

设置项说明

下表列出了可调整的设置项、示例值、数据类型与含义：

名称	示例值	数据类型	说明
settings_version	'0.0.4'	str	Ultralytics 设置版本号（区别于 pip 包版本号）
datasets_dir	'/path/to/datasets'	str	数据集存放目录
weights_dir	'/path/to/weights'	str	模型权重存放目录
runs_dir	'/path/to/runs'	str	实验运行结果存放目录
uuid	'a1b2c3d4'	str	当前设置的唯一标识符
sync	True	bool	是否向 Ultralytics HUB 同步分析数据与崩溃信息
api_key	''	str	Ultralytics HUB API Key
clearml	True	bool	是否使用 ClearML 日志记录
comet	True	bool	是否使用 Comet ML 进行实验跟踪与可视化
dvc	True	bool	是否使用 DVC 进行实验跟踪与版本控制
hub	True	bool	是否启用 Ultralytics HUB 集成
mlflow	True	bool	是否使用 MLFlow 进行实验跟踪
neptune	True	bool	是否使用 Neptune 进行实验跟踪
raytune	True	bool	是否使用 Ray Tune 进行超参数调优
tensorboard	True	bool	是否使用 TensorBoard 进行可视化
wandb	True	bool	是否使用 Weights & Biases 日志记录

上述 datasets_dir、weights_dir、runs_dir 三个路径在 utils 初始化阶段 即被读取并生成为全局常量 DATASETS_DIR、WEIGHTS_DIR、RUNS_DIR，贯穿整个训练与推理流程，因此在开展新实验前确认这些设置是否正确配置尤为重要。相关日志与实验跟踪集成的回调实现可在 utils/callbacks 目录中查阅。

小结

本文完整覆盖了 YOLOv10 的入门路径：通过 pip、conda、Git 或 Docker 完成环境安装；使用 yolo TASK MODE ARGS 语法在终端完成训练、预测、验证、导出及环境自检；在 Python 项目中以几行代码集成模型全流程；并通过 SettingsManager 精细控制数据集、权重、运行目录与各实验跟踪工具的开关。掌握这些基础操作后，即可进一步阅读 配置指南 定制训练参数，或按任务类型深入 检测、分割 等专项文档。