如果你是第一次接触目标检测打开 YOLO 相关教程时十有八九会卡在同一个位置环境配置。网上教程动不动就是 CUDA、cuDNN、显卡驱动、CUDA toolkit 版本匹配还没开始跑代码先被环境劝退。其实对于只想跑通第一次预测、理解 YOLO 基本流程的同学来说根本不需要 GPU。一台普通电脑安装 Python 3.11装好 CPU 版本的 PyTorch 和 Ultralytics就能把目标检测跑起来。先给一个明确判断CPU 跑 YOLO 不是为了追求帧率而是为了低门槛学习和验证流程。只要你的任务不是实时视频检测、不是训练大模型CPU 方案完全够用。读完这篇文章你会知道自己应该选 YOLOv8 还是 YOLO11会动手配置 Python 3.11 虚拟环境会安装 CPU 版 PyTorch 和 Ultralytics最终用一张图片跑出目标检测框并知道常见的坑在哪里。这里还要先澄清一个容易误导新手的地方网上经常出现“YOLO26”“YOLO11”“YOLOv8”这类标题其实在 Ultralytics 官方主线里目前大家日常使用的是 YOLOv8 和 YOLO11 两个大版本其他很多叫法来自社区二次开发或视频课程的自定义命名。本文以 YOLOv8 和 YOLO11 为例两者的环境配置流程几乎完全一致你只要学会一套就能覆盖绝大多数场景。1. 为什么要写这一篇CPU 环境真的能跑 YOLO 吗很多零基础读者有一个先入为主的想法目标检测这种“深度学习”方向必须要 GPU否则没法做。这个说法在训练大模型时基本成立但在学习和推理阶段并不准确。YOLO 本身是轻量级目标检测算法的代表官方提供了 n、s、m、l、x 等不同大小的模型权重其中以 n 结尾的 nano 版本参数量非常小在 CPU 上做单张图片预测通常只需要数秒到十秒级别完全能用来跑通流程。因为门槛低所以 CPU 环境反而是 YOLO 新手最应该先掌握的路线。它不需要你去折腾显卡驱动和 CUDA 版本匹配不需要考虑显存大小也不需要担心 GPU 被其他进程占用。你只需要把 Python 环境配好安装几个库下载一个权重文件就能看到目标检测效果。这种“最小可行路径”对理解模型怎么加载、图片怎么预处理、推理结果怎么解析非常有帮助。同时CPU 环境也是调试环境。实际企业项目中算法工程师的训练机可能有高性能 GPU但推理部署可能落在 CPU 服务器、边缘设备甚至 ARM 开发板上。你在自己电脑的 CPU 上先把流程跑通后面再切换到 GPU 服务器或部署环境思路是完全一致的只是计算设备不同。这也是为什么我不建议新手一上来就租 GPU 云服务器先把基础跑通再花钱买算力才是最合理的路径。2. YOLOv8 与 YOLO11版本到底怎么选在 Ultralytics 生态里YOLOv8 并不仅仅是 YOLOv5 的简单升级而是对整个训练、验证、预测、导出流程做了一次统一。它把不同任务检测、实例分割、姿态估计、分类都整合在同一个框架里API 也保持一致。YOLO11 是后续推出的新版本继续沿用了这套框架但对网络结构、训练效率、检测精度等做了改进。对新手来说这两个版本的“环境配置方式”几乎没有差别因为它们都通过同一个ultralyticsPython 包提供能力。从实际选择上看我更推荐新同学直接使用 YOLO11。原因很简单官方文档和示例都在逐渐向新版本倾斜你照着官方示例写代码时遇到的教程过时问题会少一些。当然如果你的课程设计、毕业设计或团队项目指定了 YOLOv8也完全可以继续用YOLOv8 的生态成熟度更高网络上中文资料也更丰富遇到问题时更容易搜到解决方案。下面用表格简单对比一下方便你快速判断对比维度YOLOv8YOLO11发布时间2023 年初2024 年发布模型文件示例yolov8n.ptyolo11n.pt支持的 Python 版本3.8 及以上3.8 及以上CPU 推理速度快但更依赖具体模型大小整体更优n 版本依然轻量任务支持检测、分割、姿态、分类检测、分割、姿态、分类API 使用方式通过 ultralytics 包调用通过 ultralytics 包调用适合人群老项目、课程指定、中文资料多新项目、官方文档优先这里要强调一个细节YOLOv8 和 YOLO11 虽然模型文件后缀都是.pt但不同版本的权重文件对应的模型结构不同不要把yolov8n.pt传给 YOLO11 的代码逻辑去加载。严格来说Ultralytics 会检查权重文件与代码的兼容性如果混用控制台会报错或者行为异常。新手最常见的错误之一就是照着一个 YOLOv8 教程写代码但下载的是 YOLO11 的权重或者反过来导致加载模型时报错。3. 环境准备与前置条件在开始安装之前需要先把基础环境准备好。本文的目标是“零基础跑通”所以我会把环境要求写到最低避免因为硬件条件不足而中断。操作系统方面Windows 10/11 和主流 Linux 发行版都可以macOS 也能跑但如果有条件优先使用 Windows 或 Linux。Python 版本建议使用 Python 3.11这也是标题里特别提到的版本。Python 3.11 在兼容性和性能之间做了比较好的平衡同时是 PyTorch 官方轮子覆盖比较完整的版本。如果你电脑上已经安装了 Python 3.8 到 3.12 之间的其他版本也基本没问题但为了避免意外强烈建议为本文单独创建虚拟环境而不是直接用系统 Python。工具链方面推荐安装 Anaconda 或 Miniconda。Anaconda 是很多深度学习教程的标配它集成了 Python、conda 包管理器以及大量常用科学计算库优点是省心缺点是体积大。Miniconda 更轻量只包含 conda 和 Python需要什么再装什么更适合喜欢自己控制环境的读者。如果你不想用 conda使用 Python 自带的venv模块也可以但 conda 在创建不同 Python 版本环境时更灵活所以我下面的步骤以 conda 为主同时会补充 venv 的命令。硬件方面CPU 至少是双核内存建议 8GB 以上。如果你只有 8GB 内存也能跑但建议不要同时打开太多浏览器标签页。磁盘空间至少预留 5GB 左右因为 PyTorch CPU 版、ultralytics 依赖以及模型权重都会占用空间。这里不需要配置 GPU也不涉及 CUDA。如果你后来想用 GPU只需额外安装对应版本的 PyTorch但本文不展开。还有一个小提示如果你使用的是公司电脑或受限网络环境安装包下载可能较慢建议先确认能正常访问 Python 包索引源。如果下载慢后续可以切换为国内镜像源我在后面章节会给出具体方法。4. 创建 Python 3.11 虚拟环境环境配置的第一步是创建独立的虚拟环境。为什么要单独创建因为深度学习项目的依赖往往和系统其他项目冲突例如ultralytics会安装很多依赖库如果用系统 Python 直接安装可能会覆盖或破坏其他项目的环境。虚拟环境能把 YOLO 所需的 Python 版本和依赖隔离在一个独立空间里项目删了也不会影响系统。如果你使用 conda打开命令行工具。Windows 用户可以打开 Anaconda Prompt 或 Windows TerminalLinux 用户直接打开终端然后执行conda create -n yolo python3.11这条命令会创建一个名为yolo的虚拟环境并指定使用 Python 3.11。创建过程中会询问是否继续输入y确认即可。创建完成后激活环境conda activate yolo激活后命令行提示符应该会变成(yolo) PS C:\...或(yolo) userhost:~$前面的(yolo)表示你已经进入了虚拟环境。如果激活失败先检查你是否已经运行过conda init或者在 Windows 上有没有正确初始化 conda。如果你不想使用 conda使用 Python 自带的虚拟环境模块也可以。在项目目录下执行python -m venv venv然后在 Windows 上激活venv\Scripts\activate在 Linux/macOS 上激活source venv/bin/activate激活之后后续所有的安装命令都要在这个环境内执行这一点很重要。很多新手在安装时报各种错误最后发现是命令在系统 Python 里跑根本没有进入虚拟环境导致安装包和运行环境完全分离。进入环境后先确认 Python 版本是否正确python --version如果输出包含Python 3.11说明环境创建成功。接下来我们安装深度学习框架 PyTorch。5. 安装 CPU 版 PyTorchPyTorch 是 YOLO 模型运行的核心计算框架。在 CPU 环境下我们需要安装不带 CUDA 支持的 CPU 版本。这里的“不带 CUDA”不是缺点而是为了减少不必要的体积和依赖。CPU 版 PyTorch 和 GPU 版在代码层面几乎没有区别只是底层计算时使用的是 CPU 还是 GPU。在激活虚拟环境后执行下面的命令安装 PyTorch CPU 版pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu这条命令中的--index-url https://download.pytorch.org/whl/cpu会让 pip 从 PyTorch 官方 CPU 轮子仓库下载。安装完成后可以通过下面的命令验证是否成功python -c import torch; print(torch.__version__); print(torch.cuda.is_available())正常情况下第一行会输出类似2.x.x的版本号第二行输出False。torch.cuda.is_available()返回False是 CPU 版的正常表现说明当前环境没有使用 CUDA。如果你看到输出True说明你装的是 GPU 版但不影响后续使用。这里有一个很容易踩的坑直接运行pip install torch时pip 默认会从 PyPI 下载安装包在 Windows 上PyPI 的 torch 包体积非常大而且可能默认包含 CUDA 支持导致下载时间很长。用上面这条 CPU index 命令下载体积更小安装速度更快。如果你的网络访问download.pytorch.org比较慢可以临时使用国内镜像源但要注意镜像源对 PyTorch CPU 轮子的同步情况不建议新手在安装 torch 时同时混用多个源。安装完成 torch 后再安装ultralytics包。6. 安装 Ultralytics 并准备模型权重Ultralytics 是官方维护的 YOLO 工具包它封装了模型加载、训练、验证、预测和导出等功能。你不需要手动写 YOLO 网络结构代码只需要导入这个包并调用 API 即可。在激活虚拟环境后执行pip install ultralytics这个命令会安装最新版本的 ultralytics同时会自动安装一些依赖库比如 numpy、opencv-python、matplotlib、pandas 等。等待安装完成后可以检查版本pip show ultralytics或者直接在 Python 中查看python -c import ultralytics; print(ultralytics.__version__)当你第一次调用 YOLO 模型时ultralytics 会自动下载对应的权重文件。比如你使用yolo11n.pt它会在第一次运行命令时自动从官方服务器下载 nano 版本权重。问题是自动下载依赖网络有些读者在首次运行时因为网络原因下载失败导致程序卡住。为了避免这个问题我建议你提前手动下载权重文件并放到当前项目目录下。权重文件的下载地址可以从 Ultralytics 官方 GitHub 仓库的 releases 页面查找。以 YOLO11 为例如果你是学习用途下载yolo11n.pt即可这个文件大小为几 MB 到十几 MB 不等CPU 推理速度最快。如果你想体验更高的精度可以下载yolo11m.pt或yolo11l.pt但 CPU 推理速度会明显变慢不建议新手一开始就用大模型。把下载好的权重文件放到一个固定目录比如D:\yolo_project\weights\。后面在代码里引用模型路径时优先使用绝对路径或基于项目目录的相对路径避免因为当前工作目录不对而找不到文件。mkdir weights # 将 yolo11n.pt 或 yolov8n.pt 放入 weights 目录现在我们的环境已经具备运行 YOLO 推理的条件。下面进入最激动人心的部分写代码跑首次预测。7. 首次预测用 Python 代码跑通我在这个阶段只展示最小代码流程目的是让你先看到效果后面再逐步扩展。创建一个项目目录例如yolo_first_predict在该目录下创建一个 Python 文件命名为predict.py。文件内容如下# 文件路径yolo_first_predict/predict.py from ultralytics import YOLO # 1. 加载模型权重 # 如果你把权重文件放在 weights 目录下可以写模型文件路径 model YOLO(weights/yolo11n.pt) # 2. 对图片进行预测 # 将下面的图片路径替换为你电脑上真实存在的图片路径 results model(test.jpg) # 3. 展示结果 # results 是一个列表通常我们取第一张图的结果 results[0].show()运行方式在虚拟环境已经激活、当前目录位于yolo_first_predict的前提下执行python predict.py如果一切正常程序会加载模型对test.jpg图片进行推理然后弹出一个窗口显示检测结果。窗口里的每张检测到的目标都会被画上一个矩形框框上方标注了类别名称和置信度。这里解释一下代码的关键点。YOLO(weights/yolo11n.pt)表示加载官方权重文件并初始化一个 YOLO 模型对象。如果你本地没有这个文件ultralytics 会自动下载但为了避免网络问题我建议你提前下载好。model(test.jpg)这一行是对图片执行推理实际上会经历图片预处理、模型前向计算、后处理解析等步骤最终返回一个Results列表。results[0]表示第一张图片的检测结果results[0].show()把画好框的结果展示出来方便你用肉眼确认。如果你运行predict.py后没有弹出图片窗口而是提示保存了图片也不用担心这通常是因为运行环境缺少图形界面或者代码里没有显示窗口的权限。此时可以使用save参数保存结果图片# 文件路径yolo_first_predict/predict.py from ultralytics import YOLO model YOLO(weights/yolo11n.pt) results model(test.jpg) # 结果保存到 runs/detect/predict 目录 results[0].save(result.jpg)运行后你会在项目目录下看到result.jpg这张图片上已经画好了检测框。这一步很重要因为你至少能够确认模型加载成功、图片读取成功、推理执行成功、结果保存成功。任何一个环节有问题都会在控制台输出报错信息这也是我们后面排查问题的基础。8. 使用命令行方式预测并验证效果除了写 Python 脚本ultralytics 还提供命令行工具。对于只想快速验证一张图、不打算写代码的同学命令行更方便。在虚拟环境激活后执行yolo predict modelweights/yolo11n.pt sourcetest.jpg这条命令的效果和上面的 Python 代码是一样的。模型权重、输入图片、输出结果的关系都通过参数指定。默认情况下预测结果会保存到runs/detect/predict目录目录下会有test.jpg的画框版本。如果多次运行目录名会依次变成predict2、predict3避免覆盖前面的结果。验证成功的关键标志是你能够看到一个包含检测框的结果文件。具体怎么判断打开生成的结果图片如果原本普通的照片上出现了几个矩形框并且框上有类似person 0.87、car 0.92这样的标签说明目标检测流程已经跑通。如果结果图片上没有框可能是图片本身没有检测目标可以换一张更常见的照片比如包含行人、车辆、手机、猫狗的图片。此时你还可以尝试使用 YOLOv8 的权重。把yolo11n.pt替换成yolov8n.pt命令变为yolo predict modelweights/yolov8n.pt sourcetest.jpg你会发现命令格式没有变化只是权重文件不同。这就是 YOLOv8 和 YOLO11 共用同一套环境的体现。如果你希望把推理过程输出到终端可以加上verboseTrue参数如果你希望批量处理一个文件夹里的所有图片可以把source指向文件夹yolo predict modelweights/yolo11n.pt source./images saveTrue其中saveTrue表示保存结果图片。默认情况下命令行模式已经保存结果所以这个参数主要是提醒作用。通过命令行方式你可以快速体会 YOLO 的预测流程不需要写一行 Python 代码。9. 运行结果与效果验证当结果图片出现检测框后整个环境配置的任务基本完成了。但“能跑”和“验证正确”是两码事。下面给出一个比较完整的验证思路帮助你在后续的 YOLO 项目里判断预测是否可靠。第一个维度是确认输出文件结构。使用命令行预测后在项目目录下查看runs/detect/文件夹。如果是第一次运行里面会有predict子目录打开后能看到一张或若干张结果图片。如果多次运行会生成predict2、predict3等目录。这种按次递增目录的设计方便你对比不同模型或不同参数下的效果也避免误删之前的预测结果。第二个维度是检查终端日志。运行预测时终端会输出模型参数、推理耗时、检测目标数量等信息。例如日志中会出现Speed: 0.5ms preprocess, 500.0ms inference, 1.0ms postprocess之类的统计信息其中inference表示模型前向推理耗时。CPU 环境下不同机器耗时差异很大从几百毫秒到几秒都是正常的。如果耗时异常长达到几十秒甚至几分钟说明你的电脑配置较低、图片分辨率过高或者模型权重太大建议换成 n 系列模型或者先对图片做缩放。第三个维度是检查检测框的合理性。打开结果图片后你可以观察检测框是否准确包围目标。比如一张人车混行的街景图正常结果应该包含 person、car 等类别且框的位置基本贴合目标。如果一个框出现在完全没有目标的位置或者类别识别错了可能是模型对小物体、遮挡目标、稀有类别的敏感度不足这是 YOLO 模型本身的能力限制不代表环境有问题。如果运行后没有生成任何结果需要按以下顺序排查先看终端有没有报错再看输入图片路径是否正确再看当前工作目录是否是项目目录最后看权重文件是否损坏可以重新下载yolo11n.pt再试一次。10. 常见问题与排查思路环境配置阶段读者遇到最多的问题集中在下表中。我按“问题现象、可能原因、排查方式、解决方案”四个维度整理。问题现象可能原因排查方式解决方案conda命令无法识别conda 未初始化或未安装执行conda --version检查安装路径重装 Miniconda或执行conda init后重启终端运行python predict.py报ModuleNotFoundError: No module named ultralytics没有在虚拟环境中安装 ultralytics检查命令行提示符是否显示(yolo)先激活 conda 环境再执行pip install ultralytics安装 PyTorch 时下载太慢网络问题或默认从 PyPI 下载检查 pip 输出中的下载地址使用 CPU 官方索引地址--index-url https://download.pytorch.org/whl/cpu模型权重下载失败本地无权重文件且网络受限观察日志是否有下载进度手动下载权重文件放到weights目录并通过路径引用torch.cuda.is_available()返回 True安装到了带 CUDA 的包检查安装命令和信息CPU 环境不需要处理不影响本文流程运行图片预测时提示找不到图片图片路径错误检查当前工作目录和文件是否存在使用绝对路径或将图片放到项目目录下CPU 推理速度非常慢模型选择过大、图片过大、CPU 性能不足观察终端日志中的推理耗时换用yolo11n.pt或把图片尺寸缩小到 640x640保存的图片是空白或全黑权重文件与模型代码不匹配查看终端是否有加载错误重新下载对应版本的权重文件show()没有弹出窗口无图形界面或窗口被系统拦截检查运行环境改用results[0].save(result.jpg)保存结果内存不足导致进程被杀图片分辨率过高或模型过大查看系统内存占用使用小图、小模型增加虚拟内存或关闭其他程序这十个问题是 CPU 环境下比较典型的问题。从这里可以看出大部分问题的根源都集中在“环境是否隔离”“依赖是否齐全”“路径是否正确”“权重是否匹配”这四个方面。遇到报错时先别急着重装把报错信息完整读一遍尤其是最后几行通常已经指出了问题所在。11. 最佳实践与工程建议跑通首次预测后你可以继续深入学习但在此之前我建议先养成一些好习惯避免在后续项目中踩坑。第一所有 YOLO 项目都使用独立虚拟环境。不要在一个 conda 环境里同时安装多个深度学习框架的依赖否则很容易出现版本冲突。给每个项目单独创建环境并建议在项目目录下放一个requirements.txt文件记录当前环境的包版本。这样别人拉取你的代码后执行pip install -r requirements.txt就能还原环境。第二权重文件不要散落在项目根目录。推荐建立weights或models目录把不同版本的.pt文件放进去并且用固定的命名规则例如yolo11n.pt、yolov8n.pt、yolov8m.pt。如果权重文件很多建议带上版本号或日期避免混淆。第三输入图片和输出结果要分开管理。输入图片建议放images目录输出结果默认在runs/detect下可以定期清理旧的runs目录因为每次预测都会生成一个子目录时间长了会占用不少磁盘空间。第四代码里尽量使用路径参数而不是写死绝对路径。比如下面这种写法更方便复用# 文件路径yolo_first_predict/predict.py from ultralytics import YOLO MODEL_PATH weights/yolo11n.pt SOURCE_PATH images/test.jpg model YOLO(MODEL_PATH) results model(SOURCE_PATH) results[0].save(result.jpg)第五从 CPU 迁移到 GPU 时不需要改代码。你只需要重新安装对应 CUDA 版本的 PyTorch并把模型权重放到同一目录其他逻辑完全一致。在 GPU 服务器上ultralytics 会优先使用 GPU 推理你也可以通过devicecpu或device0参数手动指定设备。第六涉及模型文件和数据时要注意版权和隐私。不要下载来源不明的.pt权重文件不要上传未经授权的人脸照片或隐私图片到在线检测服务。正确做法是训练数据使用公开数据集或自己采集授权的数据模型文件从官方仓库或可信源下载。第七如果你是课程设计或毕业设计建议在跑通预测后继续按照官方文档完成一个“小数据集训练”实验。CPU 上训练小规模数据集是可以的只是速度慢建议使用yolo11n.pt做预训练权重数据集控制在几百张图片以内训练轮次控制在 50 轮以内。这能让你完整理解训练、验证、测试的闭环。12. 总结与下一步学习方向到目前为止你已经完成了一次完整的 YOLO 环境配置和首次预测。你掌握了如何创建 Python 3.11 虚拟环境、如何安装 CPU 版 PyTorch、如何安装 Ultralytics、如何准备模型权重、如何通过 Python 代码或命令行跑通图片预测并且知道了 CPU 环境下最常见的十类问题。对零基础读者来说这套流程足以支撑后续的课程设计和入门项目。这篇文章没有覆盖的内容包括数据集标注、模型训练参数调优、模型导出与量化部署、TensorRT 加速、Flask Web 服务封装等。如果你接着往下走我建议的学习顺序是先在官方 Detect 示例上跑通训练再尝试用自己的图片数据集训练一个自定义目标检测器然后导出 ONNX 模型并接入一个 Web 端或桌面端演示。别看网上各种 YOLO 变体很多核心流程都是一样的你已经有了环境基础后面只是在这些基础上不断增加数据处理、工程封装和部署优化。当你第一次看到自己跑出来的检测框时可以顺手收藏这篇文章也建议把你遇到的环境问题记录下来。配置过程看起来是一堆命令其实背后是“虚拟环境隔离、深度学习框架安装、模型权重获取、推理 API 使用”这条清晰链路。抓住这条链路后续学习任何 YOLO 版本都不会再觉得手足无措。