上周帮新来的师弟配YOLOv5环境他照着好几篇教程来回折腾了三天最后卡在No module named torch和Microsoft Visual C 14.0 is required这两个报错上。我接手后把环境全部清掉重来了一遍从零开始到跑通detect.py花了一个半小时左右。事实上YOLOv5的配置难度并不高真正的坑基本集中在版本匹配、依赖安装和IDE解释器绑定这三个地方。这篇文章把我多次配置环境时验证过的完整过程写下来覆盖Anaconda、PyCharm、YOLOv5三个核心环节的选型原因、操作步骤和常见报错处理适合刚接触深度学习和目标检测的朋友直接作为操作手册使用。不管你电脑有没有NVIDIA显卡下面的步骤都能照做只是PyTorch安装那一步会有区别。1. 配置前的版本认知为什么是Anaconda、PyCharm和YOLOv5很多新手喜欢直接装个Python再装个编辑器就开始敲代码等依赖装到一半发现版本冲突又要全部推倒重来。先花几分钟搞清楚这三个工具各自承担什么角色后面会省下大量时间。1.1 三个工具分别解决什么问题Anaconda是一个Python发行版核心价值在于自带conda这个包管理和环境管理工具。它允许你在同一台机器上创建多个互相隔离的Python环境每个环境可以有不同的Python版本和包版本互不干扰。比如你需要TensorFlow 2.x搭配Python 3.7跑一个老项目又想用YOLOv5配Python 3.8做目标检测用conda就能在几分钟内把两个环境都配好切换时只需要一行命令。PyCharm是目前Windows上使用率最高的Python IDE负责写代码、调试、运行。它比VS Code对Python新手更友好的一点是解释器、虚拟环境、终端这些概念都被图形化呈现了你只要在设置里选对环境它就会自动帮你处理路径和依赖索引的问题。YOLOv5是Ultralytics团队开源的实时目标检测算法在工业界和学术界都用得非常多。相比YOLOv3、YOLOv4它在工程化方面做得最好代码结构清晰、文档齐全、训练推理一条龙环境配置本身不依赖额外的编译步骤后面提到的lapx另说这也是我拿它当新手第一个目标检测项目的核心理由。1.2 版本组合的选择逻辑版本搭配是环境配置里最容易翻车的地方光看最新版三个字是会出事的。我实际测试下来比较稳的组合是Anaconda 32023版以上均可Python 3.8或3.10PyTorch 2.xCPU版或CUDA版均可YOLOv5 master分支官方GitHub仓库Python版本这一点需要特别解释一下。YOLOv5官方说明里支持Python 3.8及以上但我在多台机器上测试发现Python 3.8的兼容性最稳尤其是搭配老版本的PyTorch时不会出现奇怪的ABI兼容问题。Python 3.10在最新的PyTorch 2.x下也没问题但如果你后续要训练自己的数据集、安装一些第三方预处理库3.8能遇到更少的坑。选Anaconda不要选MinicondaMiniconda更轻量只包含Python和conda装完只有几百MB如果你对环境的掌控力比较强Miniconda当然够用。但对新手来说Anaconda自带了几十个常用科学计算包numpy、pandas、matplotlib等省去很多单独安装的步骤所以我建议直接用Anaconda。还有一个关键认知Anaconda本身不带PyTorch也不带CUDA这三个是完全独立的东西。Anaconda管Python环境CUDA是显卡驱动的底层计算框架PyTorch是通过pip或conda安装进虚拟环境的深度学习框架。很多人混淆这些概念导致出问题时不知道怎么排查。2. Anaconda安装与镜像源配置顺序做对后面少踩一半坑Anaconda的安装本身没什么技术含量双击安装包一路Next就行。但如果忽略几个细节后面使用时会让你怀疑人生。2.1 安装Anaconda时容易被忽略的细节首先是下载渠道。Anaconda官网anaconda.com/products/distribution下载速度在国内普遍很慢我建议直接用清华TUNA镜像站的Archive页面下载安装包速度和稳定性都靠谱得多。选择Anaconda3-2023.09-0-Windows-x86_64.exe这类即可注意别下载成Linux版。安装时有三个细节必须注意安装路径不能有中文和空格。这是无数人踩过的坑。比如装在D:\软件\Anaconda或者C:\Users\小明\Anaconda3后续conda创建环境、安装依赖会莫名奇妙报路径错误排查起来非常痛苦。我的习惯是装在D:\DevTools\Anaconda3这种纯英文路径下。关于Add Anaconda3 to my PATH environment variable这个选项。新版Anaconda安装时默认是不勾选的官方建议不勾选用Anaconda Prompt来执行conda命令。但如果你选了不勾选后续在PyCharm终端里直接用conda activate就会提示找不到命令。我的做法是勾选上然后用Anaconda Prompt在用户环境变量里确认一遍如果导入有问题就手动把D:\DevTools\Anaconda3和D:\DevTools\Anaconda3\Scripts加到Path里。安装时选择Just Me还是All Users。如果你这台电脑只有自己用选Just Me就够权限问题少如果多用户共用才考虑All Users。安装完成后按Win R输入cmd打开命令提示符输入conda --version确认能正常输出版本号。如果提示找不到命令大概率是Path没配好按上面说的手动补上。2.2 换镜像源conda和pip两个源都必须改这一步非常关键不做的话后面每一步安装都会卡在等待网络响应上。Anaconda官方源的服务器在国外下载速度只有几十KB/s是常态换完国内镜像源之后能直接跑到几MB/s。conda换源的操作是在命令行里执行以下命令# 添加清华TUNA镜像源 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/cloud/pytorch/ # 设置显示通道来源 conda config --set show_channel_urls yes # 验证是否生效 conda config --show channels执行完之后conda会生成一个.condarc文件位置在用户目录下C:\Users\你的用户名\.condarc。如果你之前就已经配置过源目录下有这个文件可以手动查看或编辑。除了conda源pip的源也要换成国内镜像因为后面装PyTorch依赖的时候pip才是主力的包管理器。在命令行里执行# 永久设置pip为清华镜像源 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn # 验证 pip config list有朋友会问conda源和pip源不是一回事吗严格来说不是。conda从conda源安装包pip从PyPI安装包。虽然很多包两个源里都有但PyTorch这种大体积框架用pip直装更不容易出依赖冲突。所以两个源都配好后面不管哪条安装路径都能起飞。3. 创建虚拟环境与安装PyTorch整个配置的成败关键Anaconda装好之后接下来就是创建虚拟环境并安装YOLOv5的核心依赖PyTorch。这是整个配置过程中最关键、也最容易出错的一步。3.1 为什么必须建虚拟环境我见过不少新手偷懒直接在base环境里pip install torch装完一时爽后续想在同一个环境里跑另一个项目就悲剧了——要么版本冲突要么卸载的时候把别的依赖一起弄坏了。conda虚拟环境本质上就是一个独立的Python目录里面有自己的site-packages跟其他环境彻底隔离。创建YOLOv5专用环境后你在里面装什么都不会影响base环境或者其他项目。创建虚拟环境的命令很简单在命令行里执行# 创建名为yolov5的虚拟环境指定Python版本为3.8 conda create -n yolov5 python3.8 -y # 激活虚拟环境 conda activate yolov5激活之后命令行前缀会变成(yolov5)这说明你已经在虚拟环境里了。这时候执行python --version确认输出的是Python 3.8.x。3.2 安装PyTorch的版本选择方法PyTorch是整个环境里最容易出问题的包主要体现在CPU/GPU版本的选择上。安装前先确认你的电脑有没有NVIDIA独立显卡在命令行里执行nvidia-smi如果输出了一张显卡信息表说明有NVIDIA显卡并且表格右上角会有一个CUDA Version这就是你的驱动最高支持的CUDA版本。如果没有输出说明没有NVIDIA显卡那就老老实实装CPU版。装GPU版PyTorch时选择的CUDA版本不能高于nvidia-smi里显示的版本否则PyTorch运行时会提示CUDA初始化失败。比如你的驱动支持CUDA 12.1那装CUDA 11.8版本的PyTorch没问题反过来就不行。最稳妥的方式是打开PyTorch官网pytorch.org/get-started/locally它会根据你选择的操作系统、包管理器、CUDA版本自动生成安装命令。以Windows pip CUDA 11.8为例生成的命令是pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118如果你没有NVIDIA显卡就用CPU版pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu这里有个经验PyTorch的安装包体积很大几百MB到2GB不等就算有镜像源也可能装很久。装的时候务必保持命令行窗口不要关看到Successfully installed torch-2.x.x才算结束。如果中途报网络错误换--index-url为清华的PyTorch源重试。3.3 安装后的验证方法依赖装完先别急着装YOLOv5先做一个五分钟的验证确保PyTorch真的可用。在命令行里输入# 激活环境 conda activate yolov5 # 进入Python交互模式 python然后输入以下代码import torch print(torch.__version__) # 打印PyTorch版本 print(torch.cuda.is_available()) # 检查GPU是否可用 print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else CPU mode)如果你是GPU版本且一切正常第二行应该输出True第三行会显示你的显卡型号。只要输出的是False先别继续往下走回到前面检查是不是装了CPU版CUDA版本是不是不匹配驱动是不是没装好这一步验证很重要因为后面YOLOv5训练的时候会自动调用GPU如果GPU不可用而你没发现训练速度会慢到怀疑人生。4. PyCharm安装与解释器绑定把虚拟环境接进IDEAnaconda和PyTorch搞定后装个PyCharm写代码、看运行结果。这一步更多是IDE配置问题操作简单但很多人会卡在PyCharm里import torch还是报错上。4.1 安装PyCharm的版本选择PyCharm分专业版Professional和社区版Community。社区版是免费的功能足够日常开发和调试专业版需要授权但对Python开发来说差异主要体现在Web开发等高级功能上。我建议新手直接用社区版官方下载地址是jetbrains.com/pycharm/download/认准Windows下安装包后面的Community字样。安装过程同样注意两点安装路径不要带中文装完之后启动时选择Dont import settings保持默认配置。另外在安装选项页面把Create Desktop Shortcut64-bit launcher和Add bin folder to the PATH勾上前者方便启动后者方便在命令行里直接调用pycharm命令。4.2 配置虚拟环境作为项目解释器新建一个项目比如项目名叫yolo_test。然后进入File - Settings快捷键CtrlAltS找到Project: yolo_test - Python Interpreter在解释器下拉框选择Add Interpreter - Conda Environment - Existing Environment。在Interpreter路径那里选择你刚才创建的yolov5虚拟环境里的python.exe。在Windows上如果用Anaconda默认路径安装这个文件一般位于C:\Users\你的用户名\.conda\envs\yolov5\python.exe或者如果你自定义了conda路径D:\DevTools\Anaconda3\envs\yolov5\python.exe选好之后点击OKPyCharm会花几秒钟索引当前环境的包。完成后在代码里输入import torch如果不再出现红色波浪线说明解释器已经正确绑定。还有一个隐藏的配置项PyCharm的终端Terminal默认使用的是系统默认shell不一定会自动激活conda环境。你会发现左下角的终端里直接python去执行用的可能是base环境导致import torch报错。解决办法是在PyCharm里依次点击File - Settings - Tools - Terminal在Shell path那一栏填上cmd.exe然后在Environment variables里加上一项CONDA_DEFAULT_ENVyolov5。这样每次打开PyCharm终端它会自动激活yolov5环境。或者你嫌麻烦每次在终端里手动敲一句conda activate yolov5也行。5. YOLOv5源码获取、依赖安装与首次检测环境就绪后终于进入YOLOv5本体。这里主要分成源码获取、依赖安装、跑通检测三个步骤走完这一步你就能看到边界框出现在图片上。5.1 获取YOLOv5源码的常用方式YOLOv5代码托管在GitHub上仓库地址是github.com/ultralytics/yolov5。官方推荐的获取方式是用git克隆# 进入你的工作目录如 D:\yolo cd /d D:\yolo # 克隆源码 git clone https://github.com/ultralytics/yolov5.git如果网络不好、克隆慢有两个替代方案从GitHub页面直接下载ZIP压缩包解压后同样能用只是无法直接git pull更新使用国内Gitee的YOLOv5镜像仓库命令是git clone https://gitee.com/mirrors/yolov5.git速度会快很多代码内容和GitHub同步。下载完进入yolov5目录能看到detect.py、train.py、models/、data/这些文件和文件夹。其中detect.py是推理脚本train.py是训练脚本data/images里自带了两张测试图片bus.jpg和zidane.jpg后面直接用它们验证环境就够了。5.2 requirements.txt的安装陷阱YOLOv5根目录下有一个requirements.txt里面列出了运行所需的全部Python包。理论上执行一句pip install -r requirements.txt就能装完但实际操作中几乎每个新手都会在这里踩坑坑点集中在几个地方第一个坑某些包特别是lapx0.5.2在Windows上需要C编译环境而大多数人电脑上并没有安装Visual Studio Build Tools于是pip会在安装lapx时报出经典的Microsoft Visual C 14.0 is required错误。第二个坑requirements.txt里没有显式写出PyTorch所以如果你先执行它再单独装torch顺序反了会导致torch和torchvision版本对不上因为torchvision安装时会检查已安装torch的版本。我实际操作时的顺序是先按第3章装好PyTorch再执行依赖安装命令。执行时不要用裸pip而是直接安装# 激活环境 conda activate yolov5 # 进入源码目录 cd /d D:\yolo\yolov5 # 安装requirements.txt中的依赖 pip install -r requirements.txt如果lapx报错你有两个处理方案一是安装Visual Studio Build Toolsvisualstudio.microsoft.com/visual-cpp-build-tools/选择C桌面开发工作负载安装完成重启后再执行pip install -r requirements.txtlapx就能正常编译安装。缺点是Build Tools体积约2GB安装时间较长。二是从社区网友预编译的wheel文件入手下载lapx-0.5.2-cp38-cp38-win_amd64.whl这类文件然后本地安装。但这个方案依赖你的Python版本和系统架构找到匹配的wheel通常不太难装起来比编译快很多。我一般推荐先用这个方案装不上再装Build Tools。5.3 第一次跑通detect.py依赖装完在yolov5目录下执行python detect.py --weights yolov5s.pt --source data/images/bus.jpg第一次运行会自动下载yolov5s.pt预训练权重文件大约14MB。如果下载超时手动用浏览器打开https://github.com/ultralytics/yolov5/releases/download/v6.0/yolov5s.pt下载到yolov5目录下再执行上面的命令。正常执行时你会看到类似这样的输出detect: weights[yolov5s.pt], sourcedata/images/bus.jpg, ... image 1/1 D:\yolo\yolov5\data\images\bus.jpg: 448x640 4 persons, 1 bus, Done. (0.237s) Results saved to runs\detect\exp到这一步环境就已经全部配置成功了。去runs\detect\exp目录下打开那张bus.jpg画面上的人和巴士已经被框出来了。6. 真实踩坑记录我配了七八次环境后仍会遇到的几个报错这一章专门写报错处理。以下每个问题我都至少亲手遇到过两次按报错现象 - 原因 - 解法的顺序梳理方便你直接对照排查。6.1 No module named torch环境没切换不是依赖没装报错场景PyCharm里运行detect.py立刻报ModuleNotFoundError: No module named torch。很多人第一反应是我明明装过torch了然后重装一遍还是报错。这个问题的根源99%是解释器指向了错误的环境。最常见的情况是你在Anaconda Prompt里把torch装进了yolov5虚拟环境但PyCharm项目解释器却指向了base环境或另一个环境。排查方法是看PyCharm右下角显示的解释器路径或者在代码开头加一行print(torch.__file__)看它到底找的是哪个路径。如果确实指错了按第4章的步骤重新绑定解释器就能解决。6.2 Visual C 14.0 is requiredlapx引发的编译困扰报错场景pip install -r requirements.txt执行到一半弹出error: Microsoft Visual C 14.0 is required. Get it with Microsoft C Build Tools。这个报错的直接来源是lapx这个C扩展包它没有预编译的Windows wheel必须现场编译。编译需要MSVC编译器而普通电脑默认不装。我最早遇到时走了弯路装了个几GB的Build Tools编译时还因为Python 3.8和VC版本不匹配失败了好几次。后来我删掉Build Tools改成下载社区编译好的lapxwheel直接一条pip install lapx-0.5.2-cp38-cp38-win_amd64.whl就解决了。这里给个判断标准如果是Python 3.8 Windows x64优先找wheel如果是其他Python版本或Linux系统装Build Tools或编译工具链才是唯一的出路。6.3 torch.cuda.is_available()为FalseGPU不可用的常见原因报错场景前面验证时输出了False或者训练时提示Using CPU训练速度只有几秒一步。可能原因有三类装了CPU版PyTorch显卡驱动版本太低不支持目标CUDAPyTorch的CUDA版本高于驱动的CUDA版本。排查时先执行nvidia-smi看右上角的CUDA版本再执行python -c import torch; print(torch.__version__)看你装的PyTorch是CPU版还是CUDA版。如果输出里带cu118就是CUDA 11.8版不带才是CPU版部分旧版本输出是1.13.1这种不带后缀则说明是CPU版。不管哪种情况按第3章重新安装匹配的PyTorch版本即可。6.4 下载慢/超时镜像源的再强调报错场景git clone卡住、pip安装时反复ReadTimeoutError、权重文件下载到一半断掉。这些都是网络问题解决办法就是换源。GitHub慢用Gitee镜像克隆pip慢用清华PyPI源第2章已配好权重下载慢浏览器配合下载工具下载手动放进yolov5目录换源后仍有超时加大pip超时时间pip install --timeout 120 -r requirements.txt6.5 一个小技巧把验证步骤写成检查清单最后说一个我自己的习惯。每次配完环境我会把验证命令存成一个checklist下次换机器或帮别人配环境时照着走一遍哪里有问题直接定位conda --version python --version python -c import torch; print(torch.__version__, torch.cuda.is_available()) python -c import cv2, numpy, matplotlib, yaml; print(common deps ok)这四句命令覆盖了Anaconda本身、Python版本、PyTorch和GPU状态、常用依赖四个层面。哪一步报错就处理哪一步不用从头再翻文档。这个清单我用了两年帮别人排障时非常实用。YOLOv5环境配置的核心其实就三句话版本选对、源换好、环境指对。你照着这篇文章的步骤走正常情况下两小时内一定能看到检测框画出来。后面等你要训练自己的数据集了再来解锁train.py的那些参数也不迟。
YOLOv5环境配置全攻略：Anaconda+PyCharm+PyTorch从零到跑通
上周帮新来的师弟配YOLOv5环境他照着好几篇教程来回折腾了三天最后卡在No module named torch和Microsoft Visual C 14.0 is required这两个报错上。我接手后把环境全部清掉重来了一遍从零开始到跑通detect.py花了一个半小时左右。事实上YOLOv5的配置难度并不高真正的坑基本集中在版本匹配、依赖安装和IDE解释器绑定这三个地方。这篇文章把我多次配置环境时验证过的完整过程写下来覆盖Anaconda、PyCharm、YOLOv5三个核心环节的选型原因、操作步骤和常见报错处理适合刚接触深度学习和目标检测的朋友直接作为操作手册使用。不管你电脑有没有NVIDIA显卡下面的步骤都能照做只是PyTorch安装那一步会有区别。1. 配置前的版本认知为什么是Anaconda、PyCharm和YOLOv5很多新手喜欢直接装个Python再装个编辑器就开始敲代码等依赖装到一半发现版本冲突又要全部推倒重来。先花几分钟搞清楚这三个工具各自承担什么角色后面会省下大量时间。1.1 三个工具分别解决什么问题Anaconda是一个Python发行版核心价值在于自带conda这个包管理和环境管理工具。它允许你在同一台机器上创建多个互相隔离的Python环境每个环境可以有不同的Python版本和包版本互不干扰。比如你需要TensorFlow 2.x搭配Python 3.7跑一个老项目又想用YOLOv5配Python 3.8做目标检测用conda就能在几分钟内把两个环境都配好切换时只需要一行命令。PyCharm是目前Windows上使用率最高的Python IDE负责写代码、调试、运行。它比VS Code对Python新手更友好的一点是解释器、虚拟环境、终端这些概念都被图形化呈现了你只要在设置里选对环境它就会自动帮你处理路径和依赖索引的问题。YOLOv5是Ultralytics团队开源的实时目标检测算法在工业界和学术界都用得非常多。相比YOLOv3、YOLOv4它在工程化方面做得最好代码结构清晰、文档齐全、训练推理一条龙环境配置本身不依赖额外的编译步骤后面提到的lapx另说这也是我拿它当新手第一个目标检测项目的核心理由。1.2 版本组合的选择逻辑版本搭配是环境配置里最容易翻车的地方光看最新版三个字是会出事的。我实际测试下来比较稳的组合是Anaconda 32023版以上均可Python 3.8或3.10PyTorch 2.xCPU版或CUDA版均可YOLOv5 master分支官方GitHub仓库Python版本这一点需要特别解释一下。YOLOv5官方说明里支持Python 3.8及以上但我在多台机器上测试发现Python 3.8的兼容性最稳尤其是搭配老版本的PyTorch时不会出现奇怪的ABI兼容问题。Python 3.10在最新的PyTorch 2.x下也没问题但如果你后续要训练自己的数据集、安装一些第三方预处理库3.8能遇到更少的坑。选Anaconda不要选MinicondaMiniconda更轻量只包含Python和conda装完只有几百MB如果你对环境的掌控力比较强Miniconda当然够用。但对新手来说Anaconda自带了几十个常用科学计算包numpy、pandas、matplotlib等省去很多单独安装的步骤所以我建议直接用Anaconda。还有一个关键认知Anaconda本身不带PyTorch也不带CUDA这三个是完全独立的东西。Anaconda管Python环境CUDA是显卡驱动的底层计算框架PyTorch是通过pip或conda安装进虚拟环境的深度学习框架。很多人混淆这些概念导致出问题时不知道怎么排查。2. Anaconda安装与镜像源配置顺序做对后面少踩一半坑Anaconda的安装本身没什么技术含量双击安装包一路Next就行。但如果忽略几个细节后面使用时会让你怀疑人生。2.1 安装Anaconda时容易被忽略的细节首先是下载渠道。Anaconda官网anaconda.com/products/distribution下载速度在国内普遍很慢我建议直接用清华TUNA镜像站的Archive页面下载安装包速度和稳定性都靠谱得多。选择Anaconda3-2023.09-0-Windows-x86_64.exe这类即可注意别下载成Linux版。安装时有三个细节必须注意安装路径不能有中文和空格。这是无数人踩过的坑。比如装在D:\软件\Anaconda或者C:\Users\小明\Anaconda3后续conda创建环境、安装依赖会莫名奇妙报路径错误排查起来非常痛苦。我的习惯是装在D:\DevTools\Anaconda3这种纯英文路径下。关于Add Anaconda3 to my PATH environment variable这个选项。新版Anaconda安装时默认是不勾选的官方建议不勾选用Anaconda Prompt来执行conda命令。但如果你选了不勾选后续在PyCharm终端里直接用conda activate就会提示找不到命令。我的做法是勾选上然后用Anaconda Prompt在用户环境变量里确认一遍如果导入有问题就手动把D:\DevTools\Anaconda3和D:\DevTools\Anaconda3\Scripts加到Path里。安装时选择Just Me还是All Users。如果你这台电脑只有自己用选Just Me就够权限问题少如果多用户共用才考虑All Users。安装完成后按Win R输入cmd打开命令提示符输入conda --version确认能正常输出版本号。如果提示找不到命令大概率是Path没配好按上面说的手动补上。2.2 换镜像源conda和pip两个源都必须改这一步非常关键不做的话后面每一步安装都会卡在等待网络响应上。Anaconda官方源的服务器在国外下载速度只有几十KB/s是常态换完国内镜像源之后能直接跑到几MB/s。conda换源的操作是在命令行里执行以下命令# 添加清华TUNA镜像源 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/cloud/pytorch/ # 设置显示通道来源 conda config --set show_channel_urls yes # 验证是否生效 conda config --show channels执行完之后conda会生成一个.condarc文件位置在用户目录下C:\Users\你的用户名\.condarc。如果你之前就已经配置过源目录下有这个文件可以手动查看或编辑。除了conda源pip的源也要换成国内镜像因为后面装PyTorch依赖的时候pip才是主力的包管理器。在命令行里执行# 永久设置pip为清华镜像源 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn # 验证 pip config list有朋友会问conda源和pip源不是一回事吗严格来说不是。conda从conda源安装包pip从PyPI安装包。虽然很多包两个源里都有但PyTorch这种大体积框架用pip直装更不容易出依赖冲突。所以两个源都配好后面不管哪条安装路径都能起飞。3. 创建虚拟环境与安装PyTorch整个配置的成败关键Anaconda装好之后接下来就是创建虚拟环境并安装YOLOv5的核心依赖PyTorch。这是整个配置过程中最关键、也最容易出错的一步。3.1 为什么必须建虚拟环境我见过不少新手偷懒直接在base环境里pip install torch装完一时爽后续想在同一个环境里跑另一个项目就悲剧了——要么版本冲突要么卸载的时候把别的依赖一起弄坏了。conda虚拟环境本质上就是一个独立的Python目录里面有自己的site-packages跟其他环境彻底隔离。创建YOLOv5专用环境后你在里面装什么都不会影响base环境或者其他项目。创建虚拟环境的命令很简单在命令行里执行# 创建名为yolov5的虚拟环境指定Python版本为3.8 conda create -n yolov5 python3.8 -y # 激活虚拟环境 conda activate yolov5激活之后命令行前缀会变成(yolov5)这说明你已经在虚拟环境里了。这时候执行python --version确认输出的是Python 3.8.x。3.2 安装PyTorch的版本选择方法PyTorch是整个环境里最容易出问题的包主要体现在CPU/GPU版本的选择上。安装前先确认你的电脑有没有NVIDIA独立显卡在命令行里执行nvidia-smi如果输出了一张显卡信息表说明有NVIDIA显卡并且表格右上角会有一个CUDA Version这就是你的驱动最高支持的CUDA版本。如果没有输出说明没有NVIDIA显卡那就老老实实装CPU版。装GPU版PyTorch时选择的CUDA版本不能高于nvidia-smi里显示的版本否则PyTorch运行时会提示CUDA初始化失败。比如你的驱动支持CUDA 12.1那装CUDA 11.8版本的PyTorch没问题反过来就不行。最稳妥的方式是打开PyTorch官网pytorch.org/get-started/locally它会根据你选择的操作系统、包管理器、CUDA版本自动生成安装命令。以Windows pip CUDA 11.8为例生成的命令是pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118如果你没有NVIDIA显卡就用CPU版pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu这里有个经验PyTorch的安装包体积很大几百MB到2GB不等就算有镜像源也可能装很久。装的时候务必保持命令行窗口不要关看到Successfully installed torch-2.x.x才算结束。如果中途报网络错误换--index-url为清华的PyTorch源重试。3.3 安装后的验证方法依赖装完先别急着装YOLOv5先做一个五分钟的验证确保PyTorch真的可用。在命令行里输入# 激活环境 conda activate yolov5 # 进入Python交互模式 python然后输入以下代码import torch print(torch.__version__) # 打印PyTorch版本 print(torch.cuda.is_available()) # 检查GPU是否可用 print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else CPU mode)如果你是GPU版本且一切正常第二行应该输出True第三行会显示你的显卡型号。只要输出的是False先别继续往下走回到前面检查是不是装了CPU版CUDA版本是不是不匹配驱动是不是没装好这一步验证很重要因为后面YOLOv5训练的时候会自动调用GPU如果GPU不可用而你没发现训练速度会慢到怀疑人生。4. PyCharm安装与解释器绑定把虚拟环境接进IDEAnaconda和PyTorch搞定后装个PyCharm写代码、看运行结果。这一步更多是IDE配置问题操作简单但很多人会卡在PyCharm里import torch还是报错上。4.1 安装PyCharm的版本选择PyCharm分专业版Professional和社区版Community。社区版是免费的功能足够日常开发和调试专业版需要授权但对Python开发来说差异主要体现在Web开发等高级功能上。我建议新手直接用社区版官方下载地址是jetbrains.com/pycharm/download/认准Windows下安装包后面的Community字样。安装过程同样注意两点安装路径不要带中文装完之后启动时选择Dont import settings保持默认配置。另外在安装选项页面把Create Desktop Shortcut64-bit launcher和Add bin folder to the PATH勾上前者方便启动后者方便在命令行里直接调用pycharm命令。4.2 配置虚拟环境作为项目解释器新建一个项目比如项目名叫yolo_test。然后进入File - Settings快捷键CtrlAltS找到Project: yolo_test - Python Interpreter在解释器下拉框选择Add Interpreter - Conda Environment - Existing Environment。在Interpreter路径那里选择你刚才创建的yolov5虚拟环境里的python.exe。在Windows上如果用Anaconda默认路径安装这个文件一般位于C:\Users\你的用户名\.conda\envs\yolov5\python.exe或者如果你自定义了conda路径D:\DevTools\Anaconda3\envs\yolov5\python.exe选好之后点击OKPyCharm会花几秒钟索引当前环境的包。完成后在代码里输入import torch如果不再出现红色波浪线说明解释器已经正确绑定。还有一个隐藏的配置项PyCharm的终端Terminal默认使用的是系统默认shell不一定会自动激活conda环境。你会发现左下角的终端里直接python去执行用的可能是base环境导致import torch报错。解决办法是在PyCharm里依次点击File - Settings - Tools - Terminal在Shell path那一栏填上cmd.exe然后在Environment variables里加上一项CONDA_DEFAULT_ENVyolov5。这样每次打开PyCharm终端它会自动激活yolov5环境。或者你嫌麻烦每次在终端里手动敲一句conda activate yolov5也行。5. YOLOv5源码获取、依赖安装与首次检测环境就绪后终于进入YOLOv5本体。这里主要分成源码获取、依赖安装、跑通检测三个步骤走完这一步你就能看到边界框出现在图片上。5.1 获取YOLOv5源码的常用方式YOLOv5代码托管在GitHub上仓库地址是github.com/ultralytics/yolov5。官方推荐的获取方式是用git克隆# 进入你的工作目录如 D:\yolo cd /d D:\yolo # 克隆源码 git clone https://github.com/ultralytics/yolov5.git如果网络不好、克隆慢有两个替代方案从GitHub页面直接下载ZIP压缩包解压后同样能用只是无法直接git pull更新使用国内Gitee的YOLOv5镜像仓库命令是git clone https://gitee.com/mirrors/yolov5.git速度会快很多代码内容和GitHub同步。下载完进入yolov5目录能看到detect.py、train.py、models/、data/这些文件和文件夹。其中detect.py是推理脚本train.py是训练脚本data/images里自带了两张测试图片bus.jpg和zidane.jpg后面直接用它们验证环境就够了。5.2 requirements.txt的安装陷阱YOLOv5根目录下有一个requirements.txt里面列出了运行所需的全部Python包。理论上执行一句pip install -r requirements.txt就能装完但实际操作中几乎每个新手都会在这里踩坑坑点集中在几个地方第一个坑某些包特别是lapx0.5.2在Windows上需要C编译环境而大多数人电脑上并没有安装Visual Studio Build Tools于是pip会在安装lapx时报出经典的Microsoft Visual C 14.0 is required错误。第二个坑requirements.txt里没有显式写出PyTorch所以如果你先执行它再单独装torch顺序反了会导致torch和torchvision版本对不上因为torchvision安装时会检查已安装torch的版本。我实际操作时的顺序是先按第3章装好PyTorch再执行依赖安装命令。执行时不要用裸pip而是直接安装# 激活环境 conda activate yolov5 # 进入源码目录 cd /d D:\yolo\yolov5 # 安装requirements.txt中的依赖 pip install -r requirements.txt如果lapx报错你有两个处理方案一是安装Visual Studio Build Toolsvisualstudio.microsoft.com/visual-cpp-build-tools/选择C桌面开发工作负载安装完成重启后再执行pip install -r requirements.txtlapx就能正常编译安装。缺点是Build Tools体积约2GB安装时间较长。二是从社区网友预编译的wheel文件入手下载lapx-0.5.2-cp38-cp38-win_amd64.whl这类文件然后本地安装。但这个方案依赖你的Python版本和系统架构找到匹配的wheel通常不太难装起来比编译快很多。我一般推荐先用这个方案装不上再装Build Tools。5.3 第一次跑通detect.py依赖装完在yolov5目录下执行python detect.py --weights yolov5s.pt --source data/images/bus.jpg第一次运行会自动下载yolov5s.pt预训练权重文件大约14MB。如果下载超时手动用浏览器打开https://github.com/ultralytics/yolov5/releases/download/v6.0/yolov5s.pt下载到yolov5目录下再执行上面的命令。正常执行时你会看到类似这样的输出detect: weights[yolov5s.pt], sourcedata/images/bus.jpg, ... image 1/1 D:\yolo\yolov5\data\images\bus.jpg: 448x640 4 persons, 1 bus, Done. (0.237s) Results saved to runs\detect\exp到这一步环境就已经全部配置成功了。去runs\detect\exp目录下打开那张bus.jpg画面上的人和巴士已经被框出来了。6. 真实踩坑记录我配了七八次环境后仍会遇到的几个报错这一章专门写报错处理。以下每个问题我都至少亲手遇到过两次按报错现象 - 原因 - 解法的顺序梳理方便你直接对照排查。6.1 No module named torch环境没切换不是依赖没装报错场景PyCharm里运行detect.py立刻报ModuleNotFoundError: No module named torch。很多人第一反应是我明明装过torch了然后重装一遍还是报错。这个问题的根源99%是解释器指向了错误的环境。最常见的情况是你在Anaconda Prompt里把torch装进了yolov5虚拟环境但PyCharm项目解释器却指向了base环境或另一个环境。排查方法是看PyCharm右下角显示的解释器路径或者在代码开头加一行print(torch.__file__)看它到底找的是哪个路径。如果确实指错了按第4章的步骤重新绑定解释器就能解决。6.2 Visual C 14.0 is requiredlapx引发的编译困扰报错场景pip install -r requirements.txt执行到一半弹出error: Microsoft Visual C 14.0 is required. Get it with Microsoft C Build Tools。这个报错的直接来源是lapx这个C扩展包它没有预编译的Windows wheel必须现场编译。编译需要MSVC编译器而普通电脑默认不装。我最早遇到时走了弯路装了个几GB的Build Tools编译时还因为Python 3.8和VC版本不匹配失败了好几次。后来我删掉Build Tools改成下载社区编译好的lapxwheel直接一条pip install lapx-0.5.2-cp38-cp38-win_amd64.whl就解决了。这里给个判断标准如果是Python 3.8 Windows x64优先找wheel如果是其他Python版本或Linux系统装Build Tools或编译工具链才是唯一的出路。6.3 torch.cuda.is_available()为FalseGPU不可用的常见原因报错场景前面验证时输出了False或者训练时提示Using CPU训练速度只有几秒一步。可能原因有三类装了CPU版PyTorch显卡驱动版本太低不支持目标CUDAPyTorch的CUDA版本高于驱动的CUDA版本。排查时先执行nvidia-smi看右上角的CUDA版本再执行python -c import torch; print(torch.__version__)看你装的PyTorch是CPU版还是CUDA版。如果输出里带cu118就是CUDA 11.8版不带才是CPU版部分旧版本输出是1.13.1这种不带后缀则说明是CPU版。不管哪种情况按第3章重新安装匹配的PyTorch版本即可。6.4 下载慢/超时镜像源的再强调报错场景git clone卡住、pip安装时反复ReadTimeoutError、权重文件下载到一半断掉。这些都是网络问题解决办法就是换源。GitHub慢用Gitee镜像克隆pip慢用清华PyPI源第2章已配好权重下载慢浏览器配合下载工具下载手动放进yolov5目录换源后仍有超时加大pip超时时间pip install --timeout 120 -r requirements.txt6.5 一个小技巧把验证步骤写成检查清单最后说一个我自己的习惯。每次配完环境我会把验证命令存成一个checklist下次换机器或帮别人配环境时照着走一遍哪里有问题直接定位conda --version python --version python -c import torch; print(torch.__version__, torch.cuda.is_available()) python -c import cv2, numpy, matplotlib, yaml; print(common deps ok)这四句命令覆盖了Anaconda本身、Python版本、PyTorch和GPU状态、常用依赖四个层面。哪一步报错就处理哪一步不用从头再翻文档。这个清单我用了两年帮别人排障时非常实用。YOLOv5环境配置的核心其实就三句话版本选对、源换好、环境指对。你照着这篇文章的步骤走正常情况下两小时内一定能看到检测框画出来。后面等你要训练自己的数据集了再来解锁train.py的那些参数也不迟。
