安装 Ultralytics
在干净的环境中安装 Ultralytics，查看 yolo 检查报告以确认设备，并通过一次预测验证设置是否正确。
一次悄悄回退到 CPU 的训练可能需要一天而不是一小时，而你可能直到为时已晚才会发现。安装损坏也会以同样的方式暴露出来：在课程进行到一半时，出现导入错误或 GPU 缺失。
在这里花十分钟就能避免这两种情况。你将把 ultralytics 软件包安装到全新的环境中，逐行查看 yolo checks 报告，并运行首次 YOLO26 预测，确认所有组件都已连通。
实践操作
创建干净的环境#
ultralytics 软件包支持 Python 3.8 及更高版本，但当前版本的 PyTorch 需要 Python 3.10 或更高版本，因此新项目应使用 3.12 这样的较新版本。全新的虚拟环境可以让软件包及其依赖项与其他项目隔离：
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python --version # 3.10 or newer如果你更喜欢这些方式，Ultralytics 快速入门指南也介绍了通过 Conda 或 Docker进行相同设置的方法。
先安装正确版本的 PyTorch，再安装 Ultralytics#
Ultralytics 在 PyTorch 上运行；如果系统中尚未安装 PyTorch，pip 会安装默认版本。这个默认版本是“为什么它在用我的 CPU？”问题的主要来源，所以要先选好版本：
| 你的设备 | 先做这一步 | 然后 |
|---|---|---|
| NVIDIA GPU | 从 PyTorch 选择器安装与你的驱动匹配的 CUDA 版本 | pip install ultralytics 会一并安装 |
| Apple Silicon Mac | 无需操作：默认版本包含 MPS | pip install ultralytics |
| 仅使用 CPU | 无需操作 | pip install ultralytics |
pip install ultralytics这一条命令会安装 ultralytics Python 软件包、yolo 命令行工具，以及 OpenCV 和 NumPy 等依赖项。
查看 yolo checks 报告#
yolo checks 会打印 Ultralytics 将使用的软件版本和硬件信息。以下是 MacBook 上的实际输出，已做删减：
Ultralytics 8.4.175 🚀 Python-3.12.12 torch-2.14.1 CPU (Apple M5 Pro)
Setup complete ✅ (18 CPUs, 48.0 GB RAM, 594.4/926.3 GB disk)
OS macOS-27.0.1-arm64-arm-64bit
Python 3.12.12
Install pip
GPU None逐行说明：
Ultralytics 8.4.175 ... torch-2.14.1：软件包和 PyTorch 的版本。提交错误报告时，请附上这些信息。CPU (Apple M5 Pro)：未传入device时使用的设备。这一行最重要。Setup complete ✅：安装本身没有问题。GPU None：PyTorch 没有检测到 CUDA GPU。在 Mac 上这是预期现象；在 NVIDIA 设备上则是问题。
根据第 1 行中的设备采取相应操作：
本课程不需要 GPU：每个示例都经过设置，可在几分钟内于笔记本电脑 CPU 上完成。只有在进行全规模训练时 GPU 才很重要，通常能带来 10 倍或更高的速度提升。
用一次预测验证安装#
一次预测就能测试整个流程：它会下载 YOLO26 nano 权重、获取图像、运行模型，并写入带标注的副本。
yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpgimage 1/1 bus.jpg: 640x480 4 persons, 1 bus, 20.1ms
Speed: 0.7ms preprocess, 20.1ms inference, 0.5ms postprocess per image at shape (1, 3, 640, 480)
Results saved to runs/detect/predict640x480 4 persons, 1 bus：图像已缩放为 640×480 供模型处理，模型检测到了五个对象。20.1ms：在这台 CPU 上的推理时间。记下这个数值，作为你的第一个速度基准。runs/detect/predict：带标注的bus.jpg所在位置。再次运行该命令会生成predict-2：Ultralytics 不会覆盖之前的运行结果。
该命令中的所有默认设置——置信度、图像尺寸、保存位置——都列在配置参考中。
解决常见问题#
症状：装有 NVIDIA GPU 的机器上，yolo checks 显示 CPU 和 GPU None，训练速度慢得令人难以忍受。原因：pip 安装了仅支持 CPU 的 PyTorch。解决方法：卸载 torch 和 torchvision，从 PyTorch 选择器安装 CUDA 版本，然后重新运行 yolo checks，直到第一行显示 CUDA:0。
原因：此终端中未激活虚拟环境，因此 yolo 脚本不在 PATH 中。解决方法：每次打开新终端后，在使用 yolo 之前运行 source .venv/bin/activate（或对应的 Windows 命令）。
| 症状 | 原因 | 解决方法 |
|---|---|---|
requirements: ... not found, attempting AutoUpdate，然后运行 No module named pip | 创建环境时未安装 pip，因此 Ultralytics 无法自动安装额外的软件包 | 使用环境自带的工具安装指定软件包，例如 uv pip install lap |
| 权重或数据集下载超时 | 网络阻止了 GitHub 发布资源的访问 | 在其他位置下载一次 yolo26n.pt，然后传入其本地路径 |
PermissionError 正在写入 runs/ | 工作目录为只读 | 将 cd 写入可写的项目文件夹 |
其他问题可查看常见问题指南，其中汇总了已知问题的修复方法；Ultralytics 代码库中已关闭的问题通常也有答案——提交新问题前先搜索一下。
显示解答
python -m venv .venv
source .venv/bin/activate
# NVIDIA only: install the CUDA PyTorch build from pytorch.org first
pip install ultralytics
yolo checks
yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpgVersions: Ultralytics 8.4.175, torch 2.14.1
Device: CPU (Apple M5 Pro); use device=mps for the Apple GPU
bus.jpg: 20.1 ms inference at 640x480在笔记本电脑 CPU 上，bus.jpg 的耗时预计约为 10–60 ms；在较新的 NVIDIA GPU 上则为几毫秒。如果 yolo checks 显示了错误的设备，请先修复 PyTorch，再继续。