1. 为什么需要PyTorch和TorchVision的本地安装如果你正在学习深度学习或者你的项目需要用到计算机视觉相关的模型PyTorch和TorchVision这对组合几乎是绕不开的。PyTorch是核心的深度学习框架负责张量计算和自动微分而TorchVision则是一个专门为PyTorch服务的计算机视觉库它提供了像ResNet、VGG这样的经典预训练模型以及图像变换、数据集加载等一整套工具。通常我们通过pip install torch torchvision就能轻松搞定安装。但现实往往比理想骨感尤其是在某些特定环境下这条看似简单的命令可能会让你卡上半天。最常见的问题就是网络。无论是PyTorch官方的源还是Python官方的PyPI源在国内直接访问都可能非常缓慢甚至直接超时。你可能会遇到下载进度条卡在某个百分比一动不动最后抛出一个ReadTimeoutError或者ConnectionResetError。对于动辄几百MB甚至上GB的PyTorch CUDA版本这种体验无疑是灾难性的。另一个场景是离线环境比如公司内网的开发服务器、没有外网访问权限的生产机器或者你需要在多台配置相同的机器上部署环境。每次都从零开始在线下载既浪费时间也浪费带宽。这时候“本地安装”的价值就凸显出来了。它的核心思路很简单先在网络通畅的机器上把需要的.whl文件Python的二进制包格式下载到本地然后把这个文件拷贝到目标机器上进行安装。这个过程完全绕开了安装时的网络下载环节速度极快几乎瞬间完成并且可以确保在多台机器上安装完全一致的版本避免了因网络波动导致的版本差异问题。对于需要快速复现实验、批量部署环境的开发者来说这是一个必备技能。2. 准备工作确定版本与获取正确的.whl文件本地安装的第一步也是最关键的一步不是急着去下载而是先搞清楚你需要什么。盲目下载一个包很可能因为版本、Python版本、操作系统或CUDA版本不匹配而导致安装失败。2.1 理清版本依赖关系PyTorch、TorchVision、Python以及CUDA如果你用GPU之间存在着严格的对应关系。安装不匹配的版本是绝大多数错误的根源。确定PyTorch版本首先你需要决定安装哪个版本的PyTorch。是追求最新的特性如最新的2.x版本还是为了复现某个论文实验而需要特定的旧版本如1.7.1你可以访问 PyTorch官网的历史版本页面 查看所有版本。确定Python版本在命令行输入python --version或python3 --version记下你的Python版本例如Python 3.9.13。.whl文件的文件名里就包含了Python版本信息如cp39表示CPython 3.9。确定操作系统和位数是Windows、Linux还是macOS是64位x86_64或amd64还是32位通常现在都是64位系统。在Windows上还需要注意是Win32还是Win-AMD64。确定CUDA版本仅GPU版本需要如果你打算使用GPU进行加速这是最重要的一步。首先确保你的NVIDIA显卡驱动支持CUDA。然后在命令行输入nvidia-smi查看右上角显示的CUDA Version。注意这里显示的是驱动支持的最高CUDA版本不代表你已安装的CUDA Toolkit版本。更准确的方法是检查是否安装了CUDA Toolkit及其版本例如在命令行输入nvcc --version。PyTorch的.whl文件是针对特定CUDA版本编译的如cu116对应CUDA 11.6cu121对应CUDA 12.1。你必须下载与你的CUDA Toolkit版本匹配的PyTorch包。如果没有安装CUDA Toolkit或者只想用CPU就选择CPU版本的PyTorch文件名中通常包含cpu。确定TorchVision版本TorchVision的版本必须与PyTorch版本兼容。PyTorch官网每个版本的安装命令都会推荐对应的TorchVision版本。你也可以在 TorchVision的GitHub Release页面 查看版本对应关系。一个基本原则是主版本号尽量一致或接近。例如PyTorch 1.12.1通常搭配TorchVision 0.13.1。2.2 从可靠源下载.whl文件知道了具体版本就可以开始下载了。有以下几个可靠的源官方源不推荐直接访问https://download.pytorch.org/whl/torch_stable.html。这里列出了所有历史版本的.whl文件。但由于网络问题直接从这里下载可能很慢。国内镜像源强烈推荐为了加速下载可以使用国内的镜像站。它们同步了官方的包。清华大学镜像站https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch/win-64/(适用于Windows conda包whl包路径略有不同) 或通过pip指定镜像pip install torch torchvision -i https://pypi.tuna.tsinghua.edu.cn/simple。但我们的目标是下载whl文件可以直接在镜像站提供的PyPI镜像中搜索例如https://pypi.tuna.tsinghua.edu.cn/simple/torch/。阿里云镜像站https://mirrors.aliyun.com/pypi/simple/中国科技大学镜像站https://pypi.mirrors.ustc.edu.cn/simple/实操技巧如何精准找到下载链接最省心的办法是先在一台能联网的机器上用pip download命令。这个命令只下载包而不安装。例如你想下载PyTorch 1.12.1的CPU版本和对应的TorchVision可以这样操作pip download torch1.12.1cpu torchvision0.13.1cpu -d ./packages -i https://pypi.tuna.tsinghua.edu.cn/simple-d ./packages指定下载的包保存到当前目录的packages文件夹。执行后packages文件夹里就会出现类似torch-1.12.1cpu-cp39-cp39-win_amd64.whl和torchvision-0.13.1cpu-cp39-cp39-win_amd64.whl的文件。你可以直接将这些文件拷贝走。如果你需要GPU版本比如CUDA 11.6pip download torch1.12.1cu116 torchvision0.13.1cu116 -d ./packages -i https://pypi.tuna.tsinghua.edu.cn/simple注意cu116是版本标识的一部分。通过这种方式pip会自动帮你解析系统环境找到最匹配的.whl文件并下载避免了手动查找文件名的麻烦。3. 本地安装的核心步骤与命令详解拿到了正确的.whl文件安装过程就变得异常简单。我们将文件拷贝到目标机器比如一个离线的Windows服务器上假设放在D:\pytorch_packages目录。3.1 基础pip本地安装命令打开目标机器的命令行CMD或PowerShell导航到存放.whl文件的目录或者直接在安装命令中指定文件的完整路径。安装PyTorchpip install D:\pytorch_packages\torch-1.12.1cu116-cp39-cp39-win_amd64.whl或者先进入目录再安装cd D:\pytorch_packages pip install torch-1.12.1cu116-cp39-cp39-win_amd64.whl安装TorchVision紧接着安装TorchVisionpip会自动处理它们之间的依赖关系尽管TorchVision依赖PyTorch但因为我们先安装了PyTorch所以这里直接安装即可pip install D:\pytorch_packages\torchvision-0.13.1cu116-cp39-cp39-win_amd64.whl注意在安装TorchVision时即使本地有.whl文件pip可能仍然会尝试从网络下载一些TorchVision的依赖项比如Pillow、numpy等。为了确保完全离线最好把这些依赖包也一并下载下来。3.2 实现完全离线安装处理依赖项要实现真正的“一键离线安装”我们需要把整个依赖树都下载到本地。这可以通过pip download命令的--no-deps和-r requirements.txt组合来实现但更直接的方法是使用pip wheel来构建整个依赖链的wheel包。一个更实用的“土办法”是在一台联网机器上创建一个干净的虚拟环境然后使用pip download下载目标包及其所有依赖# 在联网机器上操作 pip download torch1.12.1cu116 torchvision0.13.1cu116 --only-binary:all: -d ./offline_packages -i https://pypi.tuna.tsinghua.edu.cn/simple--only-binary:all:强制只下载二进制包wheel避免下载源码包tar.gz which 可能在离线机器上因为缺少编译环境而安装失败。下载完成后offline_packages文件夹里会包含torch,torchvision, 以及它们依赖的numpy,Pillow,typing-extensions等所有包的.whl文件。将这些文件全部拷贝到离线机器后可以使用以下命令一次性安装所有本地包# 在离线机器上操作进入存放所有whl文件的目录 pip install --no-index --find-links./offline_packages torch1.12.1cu116 torchvision0.13.1cu116--no-index: 告诉pip不要查询PyPI索引即不使用网络。--find-links./offline_packages: 告诉pip去指定的本地目录查找包。这条命令会从offline_packages文件夹中解析并安装torch和torchvision同时自动解决并安装它们的所有本地依赖项实现完全离线安装。3.3 Windows下的常见问题与解决在Windows环境下进行本地安装你可能会遇到一些特有的问题。问题一pip不是内部或外部命令这是环境变量PATH没有包含Python的Scripts目录导致的。你需要找到Python的安装路径例如C:\Users\YourName\AppData\Local\Programs\Python\Python39和C:\Users\YourName\AppData\Local\Programs\Python\Python39\Scripts并将这两个路径添加到系统的环境变量PATH中。添加后需要重新打开命令行窗口才能生效。一个快速的验证方法是使用Python模块来运行pippython -m pip install some-package.whlpython -m pip的意思是让Python解释器直接运行pip模块这样就不依赖PATH中的pip.exe了。问题二安装时提示“找不到满足要求的版本”或“平台不支持”这几乎可以肯定是.whl文件与当前环境不匹配。请严格按照第2章的内容重新核对检查.whl文件名中的Python版本cp39是否与你的Python版本匹配。检查操作系统和架构win_amd64是否匹配。对于GPU版本检查CUDA标识cu116是否与你的CUDA Toolkit版本匹配。文件名中是否包含linux、manylinux等字样却用在Windows上问题三安装成功后导入torch报错特别是GPU版本如果安装的是CUDA版本的PyTorch导入时可能会报错例如ImportError: DLL load failed while importing _C: 找不到指定的模块。这通常是因为系统缺少必要的Visual C Redistributable运行时库。PyTorch的CUDA版本通常依赖VC 2015-2022 Redistributable。请前往微软官网下载并安装 最新版的VC可再发行组件 。安装完成后可以运行一个简单的测试脚本test_gpu.py来验证import torch print(fPyTorch版本: {torch.__version__}) print(fCUDA是否可用: {torch.cuda.is_available()}) if torch.cuda.is_available(): print(f当前CUDA设备: {torch.cuda.current_device()}) print(f设备名称: {torch.cuda.get_device_name(0)})如果torch.cuda.is_available()返回True恭喜你GPU版的PyTorch安装成功。4. 高级场景与Conda环境结合与版本管理很多深度学习开发者喜欢使用Anaconda或Miniconda来管理Python环境因为可以方便地创建隔离的环境并且conda本身也能安装PyTorch。那么pip本地安装和Conda环境能共存吗答案是肯定的而且这是一种非常灵活的实践。4.1 在Conda环境中使用pip进行本地安装Conda环境的优势在于环境隔离。你可以创建一个专为某个项目服务的环境然后在这个环境里用pip安装本地下载的PyTorch。这样做的好处是即使conda通道里没有你需要的特定PyTorch版本比如一个非常旧的、带特定CUDA版本的组合你依然可以通过pip来安装。步骤示例# 1. 创建一个新的conda环境并指定Python版本 conda create -n my_pytorch_env python3.9 # 2. 激活这个环境 conda activate my_pytorch_env # 3. 在激活的环境下使用pip进行本地安装此时这个环境的pip是独立的 pip install D:\path\to\your\torch-xxx.whl pip install D:\path\to\your\torchvision-xxx.whl重要提示在Conda环境内优先使用conda install来安装包因为conda能更好地处理环境内所有包包括一些C语言库的依赖关系。但如果conda无法提供你需要的版本再使用pip install。一个经验法则是在一个conda环境里尽量不要混用conda和pip安装同一个包比如用conda装了numpy又用pip升级numpy这可能导致依赖冲突。对于PyTorch如果决定用pip装那么相关的包如torchvision也最好都用pip安装。4.2 使用requirements.txt固化环境对于团队协作或项目部署我们需要确保所有成员、所有服务器上的环境完全一致。requirements.txt文件就是用来记录所有依赖包及其精确版本的。你可以通过以下命令将当前环境中用pip安装的所有包导出pip freeze requirements.txt这个requirements.txt文件里会包含类似torch1.12.1cu116这样的行。在离线环境下要依据这个文件安装所有依赖就需要结合我们之前提到的“下载所有依赖”的方法在联网机器上根据requirements.txt下载所有包pip download -r requirements.txt -d ./offline_packages --only-binary:all:将offline_packages文件夹和requirements.txt拷贝到离线机器。在离线机器上安装pip install --no-index --find-links./offline_packages -r requirements.txt4.3 处理复杂的版本对应与降级有时你可能需要为一个旧项目安装旧版本的PyTorch或者需要将环境从高版本降级。本地安装在这种情况下尤其有用因为你可以直接指定旧版本的.whl文件而无需担心官方源是否已经移除了该版本。例如项目需要PyTorch 1.7.1和CUDA 10.2。你可以在 PyTorch旧版本页面 找到对应的安装命令例如pip install torch1.7.1cu102 torchvision0.8.2cu102 -f https://download.pytorch.org/whl/torch_stable.html。但这条命令需要联网。我们可以用之前的方法在联网机上下载对应的whl文件。通常这些旧版本的文件依然保存在https://download.pytorch.org/whl/torch_stable.html这个索引中pip download命令配合正确的版本号依然可以找到并下载它们。降级操作如果当前环境安装了新版本需要降级直接使用pip安装旧版本的本地whl文件即可pip会自动处理卸载和安装。pip install --force-reinstall D:\packages\torch-1.7.1cu102-xxx.whl--force-reinstall参数会强制重新安装即使已经存在一个版本。5. 实战排坑从错误信息定位问题即使准备得再充分实际操作中也可能遇到各种报错。学会阅读错误信息是解决问题的关键。下面列举几个典型错误及排查思路。错误1:ERROR: torch-1.12.1cu116-cp39-cp39-win_amd64.whl is not a supported wheel on this platform.这是最经典的平台不匹配错误。信息很明确这个wheel文件不被当前平台支持。检查点1确认Python版本。cp39对应Python 3.9。如果你用的是Python 3.8就需要找cp38的包。用python -c import sys; print(sys.version)查看详细版本信息。检查点2确认操作系统和架构。win_amd64是64位Windows。如果你在32位Windows上就需要win32的包。在Linux上需要linux_x86_64或带manylinux标签的包。检查点3确认CUDA版本。如果你在只有CPU的机器上安装cu116的包也会报此错误。应换用CPU版本文件名含cpu。错误2:THC/THC.h: No such file or directory或类似编译错误这个错误通常发生在你尝试安装的是PyTorch的源码包.tar.gz而不是二进制包.whl并且你的系统缺少编译所需的依赖如Visual Studio Build Tools on Windows, 或 gcc on Linux。对于绝大多数用户我们的目标始终是下载预编译的二进制wheel包.whl避免从源码编译。确保你下载的是.whl文件并且在pip download或pip install时使用了--only-binary:all:选项如果适用。错误3: 安装成功但import torch时出现ImportError: DLL load failed如前所述这在Windows上常见尤其是GPU版本。根本原因是动态链接库DLL缺失。第一步安装VC Redistributable如前文所述。第二步检查CUDA和cuDNN的安装。确保CUDA Toolkit的bin目录例如C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.6\bin已添加到系统的PATH环境变量中。cuDNN的bin目录也需要加入PATH。第三步重启命令行终端甚至重启电脑使环境变量生效。错误4: 安装TorchVision时卡在Building wheel for pillow (setup.py) ...这表示pip正在尝试从源码编译TorchVision的一个依赖项Pillow。在离线环境下这可能会因为缺少编译环境而失败。这就是为什么我们强调要使用--only-binary:all:来强制下载所有依赖的二进制wheel包。如果你已经拿到了Pillow的二进制whl文件如Pillow-9.5.0-cp39-cp39-win_amd64.whl可以手动先安装它pip install Pillow-9.5.0-cp39-cp39-win_amd64.whl然后再安装TorchVision。通用排查流程仔细阅读错误信息错误信息的第一行和最后几行通常包含了最关键的原因。确认文件完整性下载的.whl文件是否完整可以尝试重新下载。验证环境再次三连问Python版本对吗系统对吗CUDA版本对吗简化问题尝试在一个全新的、空的虚拟环境venv或conda env中安装排除现有环境包冲突的影响。搜索错误关键词将完整的错误信息复制到搜索引擎中很大概率已经有开发者遇到过并解决了相同的问题。本地安装PyTorch和TorchVision本质上是一个“准备资源”和“精准匹配”的过程。只要前期花时间把版本对应关系理清把正确的.whl文件准备好后面的安装就是一条命令的事速度飞快且稳定可靠。对于需要频繁配置环境、或在网络受限环境下工作的开发者来说掌握这套方法能极大地提升效率把时间真正花在模型开发和算法研究上而不是无止境地等待进度条。