说实话我本来没打算专门写一篇安装教程。但最近一个月后台和粉丝群几乎每天都能收到几张报错截图内容高度一致——ModuleNotFoundError: No module named torch、torch.cuda.is_available() 返回 False、Could not find a version that satisfies the requirement torch。其中不少截图是刚装好Anaconda、连环境都没建就直接pip install torch踩出来的。PyTorch安装本身不难难的是大多数人没搞清楚自己装的是什么、该往哪个源装、装完怎么看有没有成功于是一路踩坑到怀疑人生。这篇内容我尽量往长了写但每一段都不水。我会从装之前的决策讲起把CPU版、GPU版、conda、pip、CUDA、cuDNN这些关系理顺再给出可以直接照着敲的完整命令最后整理一份高频报错排查清单。不管你是第一次接触PyTorch的新手还是已经被环境问题折磨过的老手照着这个思路走一遍大概率能少折腾半天。1. 装之前先想清楚你到底需要哪一种PyTorch很多人安装失败的根源不在操作而在决策。一上来就复制安装命令结果装出来的东西和本机环境根本对不上报错自然接踵而至。所以在动手之前先花两分钟回答三个问题。1.1 决定用CPU版还是GPU版之前先摸清自己的处境PyTorch分成CPU版和GPU版两个体系它们的安装源不一样体积不一样运行行为也不一样。没有NVIDIA显卡的机器装GPU版怎么装都装不上有显卡但不装对应驱动GPU版即使装上运行时也会静默退化成CPU模式训练速度慢得让你怀疑代码写错了。判断标准很简单如果你平时只是用PyTorch跑跑经典模型、改改结构、做课程作业、或者推理一些小型预训练模型CPU版完全够用资源占用也低。如果你要训练自己的模型、跑大规模数据、用ResNet、Transformer这类深度网络那就需要GPU版否则一个epoch能跑几个小时。提示这里说的GPU版特指NVIDIA显卡。AMD显卡用户可以去关注ROCm版本的PyTorch但生态成熟度和踩坑成本目前仍然高于NVIDIA路线本文以NVIDIA CUDA为主来展开但核心逻辑是通用的。有了这个判断你后续的安装命令才是确定的而不是随机抓取。1.2 Python版本和系统环境怎么选PyTorch每个版本都会标注它支持哪些Python版本范围。总体上来讲PyTorch 2.x对Python 3.8到3.12的支持都是比较靠得住的但我个人的实操体感是3.10和3.11是当前最稳妥的地带。3.13这类太新的版本虽然新项目也开始适配但第三方依赖库可能还没跟上容易出现装了torch之后发现某个配套库装不上、只能干瞪眼的情况。如果你用的是Anaconda我的第一建议是不要直接在base环境里装。base环境是conda自己的地盘里面有很多科学计算包你在base里反复装卸PyTorch不同版本很容易把依赖关系搞乱最后连conda update都跑不动。正确做法是单独创建虚拟环境比如conda create -n torch_env python3.11 conda activate torch_env这里的torch_env是环境名可以随便起。激活之后命令行前面会出现(torch_env)前缀这时候你再执行任何安装命令装的东西都在这个独立环境里不会污染系统全局。这也是后面排查问题时重要的隔离边界。操作系统方面Windows、Linux、macOS都能装PyTorch但macOS的GPU加速是另外一套逻辑普通的Intel/Apple Silicon Mac用户建议直接装CPU版。生产环境、服务器绝大部分是Linux安装命令基本和Windows通用但要注意离线安装时依赖的检索方式这点我在后面的离线部分单独说。1.3 Anaconda、Miniconda还是裸pip环境管理的第一道选择题这是一个绕不开的争论。我用过很长一段时间的裸pip也用过MinicondaAnaconda也不是没用过。三者的定位不一样Anaconda自带Python和几百个常用数据科学包安装包巨大适合不想费心装依赖的人。缺点是它默认给你装了一大堆用不上的东西而且base环境一旦被污染很麻烦。Miniconda只带conda环境和最小Python其他包按需安装。我个人最推荐这种方式兼顾便利和可控。裸pip系统自带Python或自己装的Python直接用pip装包。优点是轻量、纯粹、观念直白缺点是不同项目的依赖版本冲突要自己用venv管理稍麻烦。举一个具体的例子方便你理解。假设你同时在维护两个项目项目A用torch1.13.0项目B用torch2.3.0。如果用裸pip直接装后装的版本会覆盖先装的其中一个项目必挂。用conda的独立环境或者venv可以各装各的互不干扰切换项目时激活对应环境即可。所以我给你最朴素的一个建议如果还没有任何环境管理习惯直接装Miniconda然后所有PyTorch项目都建独立环境。习惯以后你会发现这为你省下的时间远远超过你安装时多敲的那几条命令。2. 显卡、驱动、CUDA之间的关系GPU版安装的核心逻辑GPU版安装是重灾区报错五花八门。但等你把下面这几个名词的逻辑彻底想明白了会发现所有报错都能归到某一类关系没对上。2.1 先听懂这套名词显卡驱动、CUDA Toolkit、cuDNN、PyTorch的CUDA版本很多教程会把“CUDA版本”这个词用得很随意导致新手分不清到底装哪个。打个比方你的NVIDIA显卡是一套设备显卡驱动是这套设备的操作系统驱动层。没有驱动系统根本认不出显卡。驱动层之上NVIDIA提供了一套开发工具包叫CUDA Toolkit里面是各种并行计算库、编译工具是开发者用来写CUDA程序的。cuDNN则是深度学习常用卷积等算子的加速库是站在CUDA肩膀上进一步优化的一层。而PyTorch官方在发布GPU版本时会针对不同CUDA版本预编译出对应的whl包比如我们经常见到的cu118、cu121、cu124分别代表适配CUDA 11.8、12.1、12.4的意思。这里有个最容易被误解的点你安装PyTorch时的CUDA版本不是你机器上GPU驱动直接暴露的那个CUDA版本而是PyTorch自带的CUDA运行时版本。PyTorch GPU版会捆绑一份CUDA运行库和cuDNN库不需要你手动去系统里装完整的CUDA Toolkit只要你的显卡驱动足够新、能兼容这个版本就行。换句话说驱动是地基PyTorch包自带运行时而cuDNN你不用自己装。很多教程里让新手下载安装好几GB的CUDA Toolkit真实使用的场景并不多。除非你要写CUDA C扩展或者编译第三方自定义算子否则没必要动那个庞然大物。2.2 怎么查自己显卡支持什么CUDA版本这条命令Windows和Linux都能用在终端里执行nvidia-smi输出会包含你的显卡型号和驱动版本右上角有一行CUDA Version: xx.x。注意这一行表示的是当前驱动最高支持的CUDA版本不是一个需要达到的绝对值。只要这个数字大于等于你想安装的PyTorch对应版本基本都能跑。举个例子如果nvidia-smi显示CUDA Version: 12.4那你安装cu121版PyTorch没问题安装cu124版也没问题。如果显示CUDA Version: 11.4那你只能装cu118或更低版本强行装cu124很容易出现运行时找不到CUDA库的报错。如果执行nvidia-smi提示不是内部或外部命令基本说明你只装了显卡、没有安装NVIDIA驱动。去NVIDIA官网下载对应型号的驱动装好重启后再继续。2.3 为什么网上示例命令会有一堆--index-url该怎么选PyTorch官方安装命令在不同的安装方式下看起来不一样。GPU版常见的安装方式是pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121这条命令的意思是不从默认的PyPI源找torch而是去PyTorch官方的源里找适配CUDA 12.1的预编译包。相应地如果你要CPU版可以用pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpuCPU版和GPU版是从两个不同通道拉取的包不能混装。最常见的坑是你先装了一个CPU版然后想换成GPU版结果直接再执行一次GPU版安装命令。此时pip发现torch已存在版本满足条件直接告诉你Requirement already satisfied根本不给你换通道。你跑验证代码的时候看到的永远是CPU版找不到GPU。正确操作是先卸载干净、再装新通道版本pip uninstall -y torch torchvision torchaudio然后重新执行目标命令。这里多花的一分钟足够你省下后面排查的两小时。2.4 驱动版本和PyTorch CUDA版本不匹配的判断与处理如果你装完GPU版后执行torch.cuda.is_available()返回False先不要怀疑是代码问题也不要急着卸载。依次检查这三层驱动层运行nvidia-smi确认系统能看到GPU。看不到说明驱动没装好。PyTorch编译目标层确认你装的是GPU版不是CPU版。判断方法是pip show torch查看Location指向的路径然后看这个包的文件名或元数据里是否包含cu字样。更直接的做法是我在验证脚本里详细测试。兼容层如果驱动版本低于PyTorch所需的最低驱动要求就会加载失败。这种情况要么升级驱动要么换成更低要求的CUDA版本。记住一条实践规律别追新追稳。不必一看到新版本就升级。你的项目之前用的cu118跑得好好的就继续用没有硬性需求不要折腾升级。我在生产环境维护过多个项目最后稳定跑下来的往往不是最新版本而是一套经过验证的老组合。3. 实操从零装好一个可运行的PyTorch环境前面讲的都是判断和原理这一节开始落地。我会按CPU版、GPU版的顺序给出完整的可复制流程并针对容易出错的地方加注释。建议你打开终端跟着做一遍。3.1 CPU版四步走假设你已经装好了Miniconda或Anaconda第一步是创建并激活环境conda create -n torch_cpu python3.11 -y conda activate torch_cpu这里用了-y参数跳过确认提示。环境名我起的是torch_cpu你可以按自己习惯改。然后从官方CPU源安装pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu如果你的网络到官方源速度不够理想可以使用国内镜像源加速。注意CPU包在PyPI上也有同名包但如果你直接pip install torch很多时候会得到一个CPU版本而你自己想装GPU版本却不知从何下手。所以明确指定--index-url是个好习惯它会通过--extra-index-url或镜像的方式来避免歧义。在安装时也可选择清华等PyPI镜像pip install torch torchvision torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple但是这样装的是默认的PyPI版本。对于CPU需求默认PyPI版本并没有问题。要GPU就务必使用官方CUDA通道或用--extra-index-url叠加。安装完成后通过一个验证脚本检验基础可用性。在Python交互环境或者脚本文件里执行import torch import torchvision print(torch.__version__) print(torchvision.__version__) x torch.randn(3, 3) print(x)能看到对应版本号和随机张量输出说明CPU版已经正常工作。3.2 GPU版完整流程从显卡检测到首次运行先查驱动和显卡nvidia-smi假设输出显示CUDA Version: 12.1或更高则可以考虑cu121这个版本。接着创建环境conda create -n torch_gpu python3.11 -y conda activate torch_gpu pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121这里你也可以按需安装其他配套库比如numpy、pandas、matplotlib等。安装包体积较大GPU版torch通常在2GB以上下载时间取决于网络。耐心等待不要中途中断。装完之后跑验证脚本建议分层次检查import torch # 第一层torch本身是否可用 print(torch.__version__) # 第二层PyTorch是否识别到CUDA汇编 print(torch.version.cuda) # 这个显示的是PyTorch自带的CUDA版本号不是驱动的 print(torch.cuda.is_available()) # 第三层GPU设备信息 if torch.cuda.is_available(): print(torch.cuda.get_device_name(0)) print(torch.cuda.device_count()) # 实际跑一个GPU上的矩阵乘法 x torch.randn(1000, 1000, devicecuda) y torch.matmul(x, x) print(GPU running OK)如果torch.version.cuda有值但torch.cuda.is_available()是False优先级最高的排查方向是驱动版本兼容性其次是权限问题。Linux下如果用的是远程服务器执行nvidia-smi没有权限也会看不到信息可以加上sudo排查。3.3 配置好后为什么建议立即进行一次完整训练冒烟测试矩阵乘法能跑不代表训练流程没问。因为torchvision的图像预处理、DataLoader的worker、模型反向传播等环节都有可能因为环境库版本不匹配而报错。我建议第一次装好环境后找一个非常小的经典模型比如CIFAR-10上的两层CNN完整跑几个batch确认loss能降、梯度能传、GPU显存占用有波动。这一步骤的目的在于把环境隐患提前暴露出来而不是等你写了几天代码之后才发现某个细节库版本不对。如果你的模型训练流程里要用到torchtext、timm、transformers也建议一并装上并做简单导入测试。很多情况下torch本体没问题问题出在配套库版本与torchvision、Python版本无法对齐。把这些配套库与PyTorch一起在环境安装阶段锁好比事后逐个排查省心得多。4. 高频报错排查清单照着这个顺序查大部分问题10分钟内解决下面这些报错是从大量真实求助里筛出来的典型代表覆盖了安装、导入、运行三个阶段的常见故障。我会给你排查顺序和解决方案记得不要跳步骤。4.1 pip下载慢、超时、连接错误现象卡在Downloading很长时间然后报超时或连接重置。原因下载源是官方PyPI或者download.pytorch.org网络路径不稳定。解法优先使用国内PyPI镜像安装CPU版或默认版pip install torch torchvision torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple如果装的是GPU版且需要从官方download.pytorch.org下载镜像效果有限可以考虑先下载whl文件再本地安装或者使用允许公司镜像、学术镜像的代理环境——这部分后续在离线安装里一并说明。另外可以在pip命令加超时时间pip install --timeout 120 torch torchvision torchaudio经验下载大文件时不要开着很弱的连接边折腾边装容易在半途中断导致缓存文件损坏。如果反复失败先pip cache purge清理缓存再重新下载。4.2ERROR: Could not find a version that satisfies the requirement torch现象pip提示找不到满足条件的torch版本后面跟着一堆“No matching distribution found”。原因最常见的是Python版本过高或过低当前pip检索的索引源中没有匹配的二进制包。比如你的Python 3.13刚发布不久时如果PyTorch官方还没有为它构建对应wheel自然找不到可装的包。解法先查看当前Python版本python --version如果Python不是3.10-3.12区间我建议直接更换环境版本不要硬扛。用conda创建3.11环境是最稳妥的方式conda create -n torch_env python3.11 -y conda activate torch_env另一个原因是索引源地址写错。检查命令中的--index-url、-i、--extra-index-url是否拼写正确、网络是否能访问。有时候某个源正常连通但里面没有对应的平台构建包也会触发这个报错换官方源重试即可。4.3 安装成功但import torch直接报缺少DLL或动态库现象Windows下提示OSError: [WinError 127] 找不到指定的程序或ImportError: DLL load failed。Linux下可能报找不到libcudnn.so.8之类的动态库。原因PyTorch运行依赖的CUDA动态运行库、cuDNN动态库缺失或版本不匹配。解法首先尝试重装GPU版torch因为安装包内的动态运行库可能在安装过程中未正确释放。其次确认是否安装过其他版本或重复版本的CUDA库导致查找路径混乱。Windows下可以检查环境变量PATH中是否存在多个CUDA路径。但在多数场景下因为PyTorch本身捆绑了运行时缺DLL较少发生一旦发生优先考虑是不是驱动过旧导致加载失败。同时排查一下是不是之前装了CPU版后来又装了GPU版造成部分文件冲突。执行彻底卸载后重装pip uninstall -y torch torchvision torchaudio pip cache purge然后重新安装目标版本装完重启Python进程不要用正在运行着的旧内核或旧解释器做验证。4.4torch.cuda.is_available()返回False但torch版本正常现象能导入torchtorch.__version__也正常但GPU检测就是False。解法先确认装的是GPU版还是CPU版。执行python -c import torch; print(torch.__version__)如果输出带cpu说明装的是CPU版直接用我前面写的方法卸载后从cuXXX源重装。如果输出带cu121等形式继续查驱动。执行nvidia-smi看是否识别GPU。Linux下如果显示No devices were found大概率是驱动没装好或GPU被占用/掉卡。检查驱动版本是否足够。比如cu121通常要求驱动版本不低于525左右当然驱动过老的可能在加载CUDA运行时就报错。Windows下如果确认前面都没问题把PyTorch相关的Python环境放到受支持的路径下排除中文或空格路径干扰。这个排查顺序是从“安装包类型”到“系统底层”层层推进的不要跳。我见过不少同学花很长时间重装显卡驱动最后发现只是装了CPU版本白白耗掉半天进度。4.5 conda创建环境时一直卡在Solving environment现象执行conda create -n torch_env python3.11后conda一直在solving environment转圈像死机一样。原因conda默认源访问不稳定或者包依赖解析过于复杂。Anaconda官方源卡顿是常见问题尤其是环境里已经有很多包时。解法更换conda国内镜像源或改用libmamba求解器。新版conda默认已经多次尝试将libmamba作为底层求解器速度提升明显。可以运行conda install -n base conda-libmamba-solver -y conda config --set solver libmamba另外如果你不需要通过conda安装torch也可以在conda创建环境时只安装Python本体通过pip安装PyTorch。这样conda的求解负担小很多很少卡顿conda create -n torch_env python3.11 -y conda activate torch_env pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu1214.6 离线安装内网隔离环境怎么把PyTorch装进去很多开发环境是物理隔离的没有外网。这种场景下不要想着在离线机器上手动一个个依赖包太容易遗漏正确姿势是准备一台同系统的联网机器用pip download把目标包和全部依赖一次性下载下来。假设你是Linux x86_64机器Python 3.11需要CUDA 12.1版本那么在一台同系统联网机器上执行pip download torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 -d ./my_packages-d指定的目录里会出现所有whl文件包括依赖项。把这个目录拷贝到离线机器上然后执行pip install --no-index --find-links./my_packages torch torchvision torchaudio--no-index告诉pip不要访问网络索引--find-links指定从本地目录找包。如果离线机器上没有Python环境你还需要提前下载好对应平台的Python或Miniconda安装包这些都提前准备好再带进去。如果没有联网机器或者版本过于老、仓库难找比如老帖子里有人问“CentOS离线安装PyTorch 1.13.0”思路完全一样找到目标版本对应的whl文件用--find-links方式安装。注意PyTorch 1.13.0是较早的版本需要和Python 3.7-3.10搭配用3.11大概率装不上这一点在查版本兼容时多留意。5. 版本搭配与延伸少走弯路的环境规划经验排查完问题之后再聊聊长期使用过程中的版本管理经验。这些经验不是从文档里抄来的而是我反复装环境、换环境、修环境攒出来的教训。5.1 环境隔离是长期维护的基础如果一个Python环境里同时存在着不同项目依赖各种冲突那总有一天会炸。我当时维护一个NLP项目用transformers新版本另一个CV项目还在用老版torchvision两者要求不同如果放在同一个conda环境里几乎寸步难行。独立环境之间就像每个人有自己的办公桌谁也不会动谁的东西这个比喻放到环境管理上非常贴切。每个项目开始前先建独立环境并顺手把环境名记到项目README里半年后你再回来看项目时能少掉很多头发。常用的记录形式是conda env list以及每个环境的导出pip freeze requirements.txt这种方式在换机器重建环境时特别有用。5.2 不要盲目追新版本锁定的价值很多人在安装时喜欢把torch、torchvision、torchaudio三个包不加版本号直接装结果隔几个月后环境里的版本和项目里导入方式不一致出现莫名其妙的警告甚至报错。我在实际项目里会固定三个核心库的版本比如pip install torch2.3.0 torchvision0.18.0 torchaudio2.3.0 --index-url https://download.pytorch.org/whl/cu121这里的版本对应关系在PyTorch官网有明确表格。一定要记住torch、torchvision、torchaudio的版本是配套发布的混搭版本很容易出现接口不兼容。如果你不知道当前该配什么版本直接去官方历史版本页面查别瞎猜。5.3 换个思路当PyTorch方案本身变得复杂时怎么办有时候不是你装错了而是你的需求超出了当前组合的舒适区。比如你想用某些国产加速卡训练模型在PyTorch主版本上会遇到大量兼容问题这种场景下需要找到硬件厂商发布的定制PyTorch版本或配套容器镜像而不是死磕官方源。此外如果你想在一台机器上同时使用多个不同CUDA版本的PyTorch深度依赖conda环境隔离这个方案完全可行但每次切换环境后要让训练逻辑确保调用的是当前环境的Python解释器而不是全局python。一个简单习惯是激活环境后用which python确认路径指向了当前conda环境。5.4 从安装走向使用的最后一步记好你的运行时版本组合我在最后分享一个我自己的工作习惯每次环境配置成功后都会在一个固定文本文件里记下来这个环境的关键版本信息包括Python版本、torch版本、CUDA版本、操作系统、显卡驱动版本。下次遇到类似环境问题翻这个记录基本能快速定位是不是哪个版本发生了变化。这个习惯在执行层面就是花半分钟运行python -c import platform, torch; print(platform.python_version(), torch.__version__, torch.version.cuda)然后把输出复制下来存档。等你哪天升级驱动、换机器、部署新环境时会感谢这个半分钟的操作。我在实际排查安装问题过程中最大的体会是绝大多数环境问题都不是“装不上”而是“信息错位”——安装者不知道目标版本对系统底层的要求系统底层也不知道当前Python环境装的是什么。安装指南能给你命令但只有理解了显卡驱动、CUDA运行时、Python环境和PyTorch版本这四者的层级关系你才可能面对新报错时不再恐慌而是有条理地一层层排查。把这套思路理清楚以后再装任何深度学习框架都不会再怕了。