📚 课程目录第2章环境搭建

2. 环境搭建

做深度学习项目，环境搭建往往是第一个坑。我见过不少同学代码写好了，结果卡在环境配置上，一折腾就是半天。YOLOv10 的环境搭建其实不算复杂，但有几个细节不注意，后面跑起来会各种报错。这一节咱们就把环境从头捋一遍。

2.1 硬件与软件前置检查

动手之前，先确认你的机器满足基本条件。别急着装东西，先看看手里的牌。

组件	推荐配置	最低配置
GPU	NVIDIA RTX 3060 及以上	NVIDIA GTX 1080
显存	8GB 及以上	4GB
系统	Ubuntu 20.04 / 22.04	Windows 10 / 11
CUDA	11.8 或 12.1	11.7
Python	3.9 - 3.11	3.8

⚠️ 注意：YOLOv10 官方推荐 Python 3.9-3.11。我试过 Python 3.12，有几个依赖包还没完全适配，会报一些奇怪的错误。建议别用最新的 Python 版本。

2.2 PyTorch 环境配置

我个人习惯用 conda 管理环境，干净、隔离、好清理。如果你还没装 Anaconda 或 Miniconda，先去官网下一个装上。

2.2.1 创建虚拟环境

conda create -n yolov10 python=3.10 -y
conda activate yolov10

环境名我取的是 yolov10，你也可以按自己喜好来。Python 3.10 是目前兼容性最好的版本，我建议就用它。

2.2.2 安装 PyTorch

去 PyTorch 官网（pytorch.org）找到对应 CUDA 版本的安装命令。这里我以 CUDA 11.8 为例：

pip install torch==2.1.0 torchvision==0.16.0 torchaudio==2.1.0 --index-url https://download.pytorch.org/whl/cu118

如果你用的是 CUDA 12.1，把 cu118 换成 cu121 就行。

💡 小技巧：安装完后，跑一下 python -c "import torch; print(torch.cuda.is_available())"。如果返回 True，说明 GPU 可用。返回 False 的话，检查 CUDA 驱动版本和 PyTorch 版本是否匹配。

我曾经在一台服务器上折腾了半天，发现是 CUDA 驱动版本太旧，PyTorch 2.x 根本认不出来。升级驱动后就好了。

2.3 YOLOv10 源码下载

YOLOv10 的源码托管在 GitHub 上。直接用 git clone 拉下来：

git clone https://github.com/THU-MIG/yolov10.git
cd yolov10

如果你网络不好，也可以去 GitHub 页面下载 ZIP 包，解压后进入目录。我个人更推荐 git clone，方便后续更新。

2.4 依赖安装

YOLOv10 的依赖写在 requirements.txt 里。直接一行命令搞定：

pip install -r requirements.txt

这里有个坑——requirements.txt 里没有把 ultralytics 写进去，但 YOLOv10 的推理部分依赖它。你需要手动装一下：

pip install ultralytics

    📌 核心依赖清单：
    torch ≥ 2.0.0 — 深度学习框架
torchvision — 图像处理工具
ultralytics — YOLO 系列工具包
opencv-python — 图像读写
numpy — 数值计算
matplotlib — 可视化
tqdm — 进度条

2.5 环境验证

装完别急着跑。先写个简单的脚本验证一下环境是否正常。在 yolov10 目录下新建一个 test_env.py：

import torch
import ultralytics
import cv2
import numpy as np

print("PyTorch version:", torch.__version__)
print("CUDA available:", torch.cuda.is_available())
print("Ultralytics version:", ultralytics.__version__)
print("OpenCV version:", cv2.__version__)

# 测试一个简单的张量运算
x = torch.randn(3, 640, 640).cuda()
print("Tensor shape:", x.shape)
print("✅ 环境验证通过！")

跑一下：

python test_env.py

如果看到 ✅ 环境验证通过！，说明环境没问题。如果报错，根据错误信息排查——大部分情况是 CUDA 版本不匹配或某个包没装全。

2.6 知识体系总览

下面这张图把环境搭建的整个流程串起来了，方便你对照检查：

2.7 常见问题与避坑指南

环境搭建过程中，有几个问题我几乎每次都会遇到。这里列出来，你碰到了直接对照解决。

pip 安装超时：国内网络问题，加国内镜像源。比如 pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
CUDA 版本不匹配：用 nvidia-smi 查看驱动支持的 CUDA 版本，然后选对应的 PyTorch 版本。别盲目装最新的。
ultralytics 导入报错：检查是否装了最新版。我遇到过旧版 ultralytics 不兼容 YOLOv10 的情况，升级到 8.0.0 以上就好了。
OpenCV 报错：如果 cv2 导入失败，试试 pip install opencv-python-headless，这个版本不依赖 GUI 库，服务器上更稳定。

⚠️ 避坑：我曾经在 Windows 上用 conda 装 PyTorch，结果 conda 自动给我装了个 CPU 版本。后来发现是 conda 源的问题。建议用 pip 装 PyTorch，别用 conda。

2.8 验证结果示例

环境配好后，跑一下官方提供的 demo 脚本，看看能不能正常推理：

yolo predict model=yolov10n.pt source=https://ultralytics.com/images/bus.jpg

如果能看到检测结果图片输出，说明环境完全 OK。如果报错，回到前面的步骤逐一排查。

嗯，环境搭建这部分就到这里。配环境是个细致活，别着急，一步步来。配好了后面就顺畅了。