Anaconda搭建YOLO目标检测环境：Windows与Linux实战指南

说出来不怕大家笑，我第一次在 Windows 上配 YOLO 运行环境时，被 CUDA、PyTorch、Python 版本这几个词来回折腾了整整两天。后来转到 Linux 服务器上又踩了一遍差不多的坑，才彻底想明白一件事：YOLO 目标检测的环境搭建，本质上不是“装软件”，而是把一个版本匹配的 Python 解释器、深度学习框架、GPU 计算库和一堆依赖包，安安静静地放进同一个隔离空间里。而这个空间，最顺手的搭建工具就是 Anaconda。

这篇文章就是把我这两次平台的经验合在一起，完整走一遍 Windows 和 Linux 下的 Anaconda 搭建 YOLO 环境的流程，包括每一步为什么要这么做、命令行到底执行了什么、报错之后往哪个方向排查。适合刚准备入坑目标检测、想在本地或者服务器上把 YOLOv5 / YOLOv8 跑起来的同学，也适合那些装到一半卡在环境里的人直接对照着排查。

1. 为什么非要用 Anaconda 来跑 YOLO

1.1 YOLO 环境的真实组成

很多人以为搭环境就是把 YOLO 代码下载下来，然后 pip install 一把梭。等报错的时候才意识到，YOLO 跑起来依赖的是一整条链路：Python 解释器负责执行代码，PyTorch 负责张量计算和反向传播，GPU 驱动之上需要 CUDA 运行时和 cuDNN 来加速卷积运算，再往上还有 numpy、opencv-python、matplotlib、tqdm、pandas 这一堆跟检测任务直接相关的 Python 库。

这条链路里任何一环的版本不对，都会出现“装了但用不了”的尴尬状态。比如 PyTorch 编译时基于 CUDA 11.8，你机器上只有 CUDA 12.1 的运行库，大部分时候能跑，但偶尔会崩；比如 numpy 版本高于某个上限，ultralytics 里某些运算就会报 _ARRAY_API not found。这类问题跟代码本身无关，纯粹是环境没有锁好版本。

Anaconda 解决的就是这件事。它自带 conda 包管理器和独立的 Python 环境，可以在同一台机器上创建多个互不干扰的“工具箱”，每个工具箱里放一套指定版本的 Python 和依赖库。对 YOLO 这种对版本敏感的深度学习项目来说，这是最稳妥的玩法。你不需要理解 conda 底层是怎么用硬链接和符号链接做隔离的，只需要知道：每个 env 就是一间独立厨房，锅里煮什么互不影响，煮坏了直接拆掉重搭也不脏系统其他地方。

1.2 版本选择的底层逻辑

创建环境时最常遇到的问题就是“我该指定哪个 Python 版本”。我的建议是：YOLOv5 和 YOLOv8 的项目，Python 3.9 或 3.10 最稳妥。官方文档说支持 3.7 以上，但 3.11、3.12 出现以来，有些第三方依赖（特别是老版本 opencv、onnx 相关的包）还没完全跟上，容易遇到 wheel 不存在的尴尬。选 Python 3.9 不是因为它最先进，而是因为它是深度学习生态里兼容性最广的版本，几乎所有的 PyTorch 发行版都有对应的预编译包。

PyTorch 版本的选择则要看你的显卡和驱动。Windows 下打开命令行执行 nvidia-smi，右上角能看到当前驱动支持的 CUDA 版本号，比如 CUDA Version: 12.4。这个数字表示你的驱动最高能用 CUDA 12.4 的运行时，所以装 PyTorch 时选 cu118 或 cu121 的预编译版本都行。不建议为了追求最新去装 cu124，因为 PyTorch 官方预编译包不一定第一时间跟进。没有 NVIDIA 显卡的机器就老实用 CPU 版，训练慢归慢，但推理一张图还是绰绰有余。

1.3 一个参考版本组合

给一个我常用的搭配，照着抄就行：

这个组合在 Windows 10 / 11 和 Ubuntu 20.04 / 22.04 上都验证过，推理和训练没遇到版本层面的硬坑。接下来分平台说具体操作。

2. Windows 下搭建流程与三个最值得记的坑

2.1 安装 Anaconda 时该勾选什么

Windows 下安装 Anaconda 基本是下一步下一步，但有一个选项要注意：安装到最后一步会有 Add Anaconda3 to my PATH environment variable，默认不勾选。我的建议是：新手直接勾上，省事；如果你系统里已经装了多个 Python，比如 Python 3.8、3.10，那就不勾，用开始菜单里的 Anaconda Prompt 进入命令行环境，避免 PATH 冲突。

装完之后验证一下。打开 CMD 或 Anaconda Prompt，输入：

bash复制conda --version
python --version

如果看到 conda 版本号和 Python 3.11 之类的输出，说明 Anaconda 自带的基础环境已经就绪。注意 Anaconda 自带的 Python 版本可能和你后面创建的环境不一样，这是正常的，不要在这里纠结。

2.2 换源：别让 conda 默认源卡死你

国内网络环境下，conda 默认源经常慢到让人怀疑人生，甚至报出下面这个经典错误：

code复制UnavailableInvalidChannel: HTTP 404 NOT FOUND for url <https://repo.anaconda.com/pkgs/msys/...>

这个 msys 频道是一个历史遗留频道，默认配置里一旦被访问，404 就会中断整个解析过程。解决方法是把 conda 源换成国内镜像，同时移除默认的 defaults 频道。以清华源为例，命令行里执行：

bash复制conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys/
conda config --set show_channel_urls yes
conda config --remove channels defaults

这里要特别说明一下：msys 频道也要加上，因为 conda create 时有些包的元数据会引用它；但前面那个 404 是因为访问了官方 repo.anaconda.com 的 msys 频道，换成清华的镜像地址就不会有这个问题。换完之后用 conda info 确认一下 channels 列表里只剩镜像地址，不是 defaults。

2.3 创建虚拟环境并安装 PyTorch

核心命令就三条：

bash复制conda create -n yolo python=3.9 -y
conda activate yolo

activate 之后，命令行提示符前面会出现 (yolo)，说明你已经进入隔离环境。接下来安装 PyTorch，这里最容易翻车。如果直接用 pip install torch，pip 默认会从 PyPI 拉一个 CPU 版本或者版本不匹配的预编译包，导致 GPU 用不上。正确做法是到 PyTorch 官网选择对应的安装命令，或者直接用官方 index-url：

bash复制pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

这条命令会安装 CUDA 11.8 预编译版本的 PyTorch。验证 GPU 是否可用：

bash复制python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

输出 True 就说明 GPU 环境已经打通了。如果你只有 CPU，就装 CPU 版本，命令是：

bash复制pip install torch torchvision

从 PyPI 默认拉下来的就是 CPU 版。安装完再跑一次上面的验证命令，torch.cuda.is_available() 返回 False 是预期结果，不要慌。

2.4 安装 YOLO 并跑通第一个推理

PyTorch 装好后，YOLO 本身的安装反而最简单。

如果用的是 YOLOv8，直接：

bash复制pip install ultralytics

然后下载一张测试图片，执行推理：

bash复制yolo predict model=yolov8n.pt source='bus.jpg'

第一次运行会下载 yolov8n.pt 权重文件，之后就能在终端看到检测结果，并生成带框的图片。

如果用的是 YOLOv5，把代码克隆下来再装依赖：

bash复制git clone https://github.com/ultralytics/yolov5
cd yolov5
pip install -r requirements.txt
python detect.py --weights yolov5s.pt --source data/images/bus.jpg

这个阶段 Windows 用户最常遇到的坑是路径问题。YOLO 的命令行参数和代码内部大量使用相对路径，如果你的项目放在中文目录或带空格的路径下，OpenCV 读取图片时可能报错。我的建议是建一个全英文、无空格的目录，比如 D:\yolo_project，所有东西都放里面，省掉一堆跟 Windows 路径解析相关的奇怪 bug。

2.5 Windows 专属问题：OpenCV DLL、激活失效、杀毒软件

第一个常见问题是 OpenCV 报 DLL load failed。这通常是因为 numpy 版本和 opencv-python 不匹配，解决办法是升级或降级 numpy：pip install numpy==1.24.4 基本能解决。第二个常见问题是 conda activate 在 CMD 里提示命令找不到，说明 conda 没初始化到当前 shell。Windows 下用 Anaconda Prompt 就没这个问题；如果非要在普通 CMD 里用，先执行 conda init cmd.exe，重开窗口再试。第三个别忽略：Windows Defender 有时会把训练过程中生成的某些临时文件当病毒隔离，导致训练中断。如果你发现训练跑着跑着突然报文件找不到，去隔离区检查一下，把项目目录加入白名单。

3. Linux 下搭建：流程相似，坑完全不同

3.1 先确认 NVIDIA 驱动，别急着装 Anaconda

Linux 下最常见的错误顺序是：先装 Anaconda、再装 PyTorch，最后一跑 torch.cuda.is_available() 返回 False，回头一查，系统里根本没有 NVIDIA 驱动。驱动是一切 GPU 计算的前提，所以第一步先执行：

bash复制nvidia-smi

如果提示 command not found，说明驱动没装。Ubuntu 下最省事的方式是：

bash复制sudo apt update
sudo apt install nvidia-driver-535

装完重启，再执行 nvidia-smi 确认能看到显卡信息和驱动版本。注意：不要在这里自己去官网下载 runfile 手动装，除非你很清楚自己在做什么。runfile 安装方式容易和系统已有的内核模块冲突，新手容易搞到进不去图形界面。另外，如果你用的是云服务器，很多云厂商提供预装 GPU 驱动的镜像，直接在购买实例时选对应镜像，能省掉这一步。

3.2 安装 Anaconda：下载、执行、配置 PATH

Linux 下安装 Anaconda 推荐用命令行方式。从清华源下载安装包速度更快：

bash复制wget https://mirrors.tuna.tsinghua.edu.cn/anaconda/archive/Anaconda3-2023.09-0-Linux-x86_64.sh
bash Anaconda3-2023.09-0-Linux-x86_64.sh

安装过程中会问是否初始化 conda，选择 yes，它会自动往 ~/.bashrc 里写入 conda 初始化脚本。安装完成后：

bash复制source ~/.bashrc
conda --version

这一步有个容易忽略的细节：如果你是通过 SSH 远程操作，安装包用 root 或其他系统用户执行后，conda 只对该用户生效，换一个用户登录就找不到 conda 命令。所以想给哪个用户用，就用哪个用户执行安装脚本。需要提醒的是，实际工作中很少有人直接拿 root 跑深度学习训练，建议创建一个普通用户，目录权限规划好再安装。

3.3 创建环境并安装 YOLO，命令和 Windows 几乎一样

进入 Linux 之后的命令其实和 Windows 高度相似：

bash复制conda create -n yolo python=3.9 -y
conda activate yolo
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
pip install ultralytics

如果你对 conda 源访问速度不满意，同样要配置国内镜像。Linux 下配置文件是 ~/.condarc，执行之前 Windows 提到的那组 conda config --add channels 命令即可。不过 Linux 下不需要特别处理 msys 频道，因为很多 Linux 包不会走到那个频道，但加上也没坏处。

这里有一个 Linux 特有的坑：不要在 conda 环境里用 sudo pip install。很多人碰到 PermissionError 之后第一反应是加 sudo，结果装进去的包进入系统 Python 目录而不是当前 conda 环境的 site-packages，等 activate 之后 import 又报错。记住一个原则：只要当前 shell 已经激活了 yolo 环境，所有 pip、conda 命令都不要加 sudo。

3.4 Linux 下的新坑：/tmp 空间不足、OpenGL 缺失、matplotlib 报错

第一个坑是 /tmp 空间不足。conda 和 pip 在安装大包时默认使用 /tmp 作为临时目录，创建 PyTorch 这种 2GB 级别的包时，如果服务器 /tmp 只有几百兆，安装到一半会报 No space left on device。解决办法是临时指定更大的临时目录：

bash复制export TMPDIR=/home/yourname/tmp

第二个坑是 OpenGL 相关的报错，通常出现在用远程服务器跑 YOLOv8 的 UI 功能或 matplotlib 画图时：

bash复制import cv2
# 可能报错：error while loading shared libraries: libGL.so.1

这是因为服务器上没有安装图形库。解决办法：

bash复制sudo apt install libgl1 libglib2.0-0

第三个坑更隐蔽。matplotlib 在没有显示器的 Linux 环境里直接 plt.show() 会报错，训练脚本有时会在最后画混淆矩阵。可以在代码里加上 import matplotlib; matplotlib.use('Agg')，让 matplotlib 直接渲染到文件而不弹窗。YOLOv8 的 CLI 工具已经处理了大部分 situation，但如果你自己写训练脚本，这个开关还是值得记住。

3.5 Windows 和 Linux 在环境管理上的核心差异

双平台都搭过之后，我的体会是：YOLO 环境的“配方”本身不分平台，区别主要在系统层前置条件。Windows 的显卡驱动由厂商自动更新，一般不会缺；Linux 则经常需要手动装驱动，而且内核升级可能导致驱动失效。Windows 的 conda 环境绑定到图形界面的 Anaconda Prompt，Linux 则绑定到 shell 配置；Windows 路径用反斜杠，Linux 用正斜杠，YOLO 的 dataloader 在 Windows 上需要更小心处理路径字符串。这些差异看起来小，但都是实际踩出来的。

另外一个重要差异是文件系统。Linux 下训练大模型，建议把数据和项目放在 SSD 或高速挂载卷上，不要放 NFS 等网络存储，否则数据加载会成为训练瓶颈。Windows 下同样要避免把项目放在 OneDrive 同步目录里，OneDrive 的实时同步会频繁触发文件锁，训练中断的元凶之一。

4. 环境自检与验证：别等训练最后一刻才报错

4.1 三步确认环境可用

环境装完了，先别急着跑训练，用三个命令确认链路是通的。第一步，确认当前处于预期的 conda 环境：

bash复制conda info --envs

看到列表里 yolo 字样的路径前有 * 号，同时命令行前缀有 (yolo)，就说明当前激活正确。第二步，确认 PyTorch 版本和 CUDA 是否可用：

bash复制python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

第三步，确认 YOLO 依赖能正常导入：

bash复制python -c "from ultralytics import YOLO; print('ok')"

这三步如果都通过，说明环境链路已经打通，剩下的就是跑数据的问题。很多人习惯直接跳到训练命令，等到训练中途才报 RuntimeError: Found no NVIDIA driver，这时候回查驱动、回查 PyTorch 版本，浪费的时间比爬都大。

4.2 用一张图做推理冒烟测试

环境自检通过后，跑一次推理冒烟测试。不要上来就用自己的数据集，先用 YOLO 官方权重和官方示例图，流程通了再换数据。

YOLOv8 的 CLI 命令：

bash复制yolo predict model=yolov8n.pt source=https://ultralytics.com/images/bus.jpg

YOLOv5 的命令：

bash复制python detect.py --weights yolov5s.pt --source data/images/bus.jpg

重点观察两点：一是终端输出里有没有 CUDA:0 字样，说明推理确实用了 GPU；二是结果图片有没有正常生成。如果这两点都没问题，可以说 YOLO 环境已经真正跑通了。

4.3 跑一轮训练做完整链路验证

推理通过不代表训练没问题，因为训练会触发更复杂的数据加载和设备调度逻辑。强烈建议跑 1 个 epoch 的冒烟训练：

YOLOv8：

bash复制yolo train data=coco128.yaml model=yolov8n.pt epochs=1 batch=2

YOLOv5：

bash复制python train.py --data coco128.yaml --weights yolov5s.pt --epochs 1 --batch-size 2

coco128 是官方自带的小型数据集，只有 128 张图，跑一个 epoch 很快。如果这个过程不报错，并且能看到 loss 数值在输出，说明数据加载、模型前向、反向传播、权重保存这几条关键路径都通了。这一步做完，之后换自己的数据集训练，就只是数据格式和标注的问题，而不是环境问题。

4.4 把环境配方存下来

环境搭好之后，最值得做的一件事是导出环境配置。以后换机器、重建环境，或者同事想复现你的环境，一份导出文件就能省掉所有手工排查时间。

bash复制conda activate yolo
pip freeze > requirements.txt
conda env export > environment.yaml

requirements.txt 记录 Python 包的精确版本，environment.yaml 则包含 conda 层面的 channel、依赖和 pip 依赖。重建环境时：

bash复制conda env create -f environment.yaml

或者只装 Python 包：

bash复制pip install -r requirements.txt

我个人的偏好是两者都导出，存到项目的 env/ 目录里，跟代码一起提交到版本库。这样不管是自己换电脑，还是项目组新同学加入，一条命令就能复现环境。

5. 日常使用中的五个高频场景

5.1 PyCharm 配置 conda 解释器

环境用 terminal 跑通了，但如果平时用 PyCharm 写代码和调试，还要让 IDE 指向同一个 conda 环境。操作路径是：File -> Settings -> Project -> Python Interpreter，点击齿轮图标选择 Add Interpreter，然后选 Conda Environment。如果 PyCharm 自动检测不到，就点 Existing environment，在 Interpreter 路径里选到你安装 Anaconda 目录下 envs/yolo/python.exe（Windows）或 envs/yolo/bin/python（Linux）。确认之后，PyCharm 底部终端和运行按钮都会使用这个环境，不会出现终端能跑、IDE 里 import 不到包的怪现象。

5.2 conda 源和 pip 源的优先级

很多人的困惑是：到底用 conda 装包还是用 pip 装包。我的原则是：PyTorch 和 CUDA 相关的东西用官方 index-url 或 conda 源装，其他依赖用 pip 装。原因很简单，PyTorch 的预编译版本和 CUDA 版本绑定，pip 用 --index-url 参数比 conda 源更精确；而 YOLO 的日常依赖（opencv、pandas、tqdm）用 pip 从 PyPI 拉是最快的。

如果 pip 下载速度慢，可以临时指定国内 PyPI 镜像：

bash复制pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

不建议把这条镜像地址永久写进 pip 配置，因为有时候需要安装一些只在官方 PyPI 上存在的预发布包，永久换源会导致这些包找不到。

5.3 多环境管理：YOLOv5 和 YOLOv8 共存

YOLOv5 和 YOLOv8 虽然都是 YOLO 家族，但依赖不完全一样。最典型的冲突是：YOLOv5 的 requirements.txt 里固定了 torch>=1.7.0，而 YOLOv8 的 ultralytics 包对某些版本的 torchvision 有特定要求。如果你只有一个环境，两个项目来回切换，经常会遇到“一个能跑另一个报错”的情况。

解决办法就是创建两个独立环境：

bash复制conda create -n yolo5 python=3.9 -y
conda create -n yolo8 python=3.9 -y

哪个项目开发，就 conda activate 哪个环境。虽然会多占用一些磁盘空间（每个环境里的 PyTorch 都是独立的几 GB），但换来的是项目之间互不干扰。深度学习项目的磁盘空间本来就该给环境留足，这点成本的收益很大。

5.4 数据与项目目录规划

环境跑通之后，目录规划会直接影响后续训练体验。我常用的结构是这样：

code复制project/
├── datasets/        # 数据集，按 dataset/annotations/images 组织
├── env/             # 环境导出文件
├── models/          # 权重文件
├── runs/            # 训练输出和推理结果
├── scripts/         # 训练和推理脚本
└── src/             # 自定义代码

数据集不要放在项目根目录下，也不要散落在桌面。YOLO 训练时会频繁读取图片，路径层级越简单越不容易出错。如果数据量很大，建议把数据集放到独立的 SSD 目录，然后用软链接映射到项目里，这样项目代码和数据集解耦，换数据集时不用改代码。

5.5 升级还是重建环境

日常使用中，总是会遇到“某个包想升级一下”的需求。我的经验是：如果只是小版本升级，比如 ultralytics 从 8.0 升到 8.1，直接 pip install -U ultralytics 就行。但如果要升级 PyTorch 大版本（比如从 1.13 升到 2.0），或者升级 Python 版本，不要在原环境上升级，直接新建一个环境重装。因为 PyTorch 和 CUDA 的绑定关系太紧密，在原环境上升级会把一些依赖库带乱，最后可能需要从头排查，花的时间比重装还多。

新建环境的成本其实很低，有了 4.4 节的环境导出文件，一条命令就能复现原环境，然后在新环境里升级想升级的包，对比验证没问题后再把旧环境删掉。这种“宁可重建不可硬升”的思路，是我在多次环境崩坏之后总结出来的血泪经验。

最后再分享一个实操中很实用的小习惯：每次搭建环境时，把执行的命令按顺序记录到一个 SETUP.md 文件里，包括换源、创建环境、装包、验证四个步骤。不要嫌麻烦，等三个月后机器换掉、或者同事问你要环境配置的时候，这份文件的价值会远远超过那几分钟的记录成本。我自己的很多项目能快速迁移，靠的就是这份“环境搭建笔记”。