清华镜像源加速pip与conda，PyTorch和CUDA安装避坑全指南

1. 先想明白镜像源到底解决什么问题1.1 为什么官方源在国内经常装不动很多朋友第一次接触清华镜像源是因为受够了 pip 和 conda 的下载速度。你在终端里敲pip install torch然后看到进度条以几十 KB/s 的速度龟速爬行最后等来一个ReadTimeoutError这种体验在深度学习环境搭建初期几乎人人都会遇到一次。问题的根源其实很简单pip 默认从 PyPI 官方源拉包conda 默认从 Anaconda 官方源拉包这些服务器都在国外跨海传输的带宽有限加上大体积的 wheel 包PyTorch 的安装包动辄两三百 MBCUDA 相关的包更大网络稍有波动就前功尽弃。清华镜像源做的事情就是把 PyPI、Anaconda 等主流软件仓库的内容定时同步到国内服务器。你访问的是pypi.tuna.tsinghua.edu.cn但拿到的包和官方源完全一致只是下载速度从几十 KB 提升到几十 MB。对于搭建 PyTorch、安装 CUDA、管理 conda 环境这类依赖大量网络传输的场景换源几乎是成本最低、收益最直接的优化手段。1.2 清华镜像源有哪些各自适合什么场景清华开源软件镜像站Tsinghua Open Source Mirror覆盖的仓库非常多但日常开发中打交道最多的只有几个先分清它们各自管什么镜像仓库访问地址主要用途PyPI 镜像https://pypi.tuna.tsinghua.edu.cn/simple给 pip 用的 Python 包索引Anaconda 镜像https://mirrors.tuna.tsinghua.edu.cn/anaconda/给 conda 用的软件包仓库Conda-Forge 镜像https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/conda 社区维护的扩展包各系统发行版镜像https://mirrors.tuna.tsinghua.edu.cn/ubuntu/等apt、yum 等系统包管理工具其中 pip 对应的 PyPI 镜像是最常用的因为无论你最终选择什么深度学习框架安装方式几乎都绕不开 pip。conda 对应的 Anaconda 镜像则稍微复杂一些后面我会专门展开讲。1.3 镜像源不是万能的这些场景它帮不上忙有一类问题是镜像源解决不了的安装时报错提示网络连接失败、显示 404 页面、或者依赖解析冲突这些大多不是源的问题而是版本匹配或者环境配置的问题。比如热词里提到的command pip install ultralytics.nn.modules.conv returned non-zero exit这明显是 pip 解析依赖失败跟换不换源关系不大。另外PyTorch 官方为特定 CUDA 版本提供的 wheel 索引地址形如https://download.pytorch.org/whl/cu118并没有被清华镜像站完整同步所以如果你想用--index-url指定 CUDA 版本安装 PyTorch清华源帮不上忙只能用官方源或者从 PyPI 走默认版本。这一点事先心里有数会少走很多弯路。2. pip 换源最简单也是收益最大的一件事2.1 pip 永久换源一次配好终身受益pip 换源有两种做法临时指定和永久配置。临时指定适合偶尔一次的操作比如pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple但如果你需要频繁安装各种 Python 包强烈建议直接写进配置文件一劳永逸。Linux 和 macOS 下配置文件路径是~/.pip/pip.confWindows 下是%APPDATA%\pip\pip.ini。没有这个文件就自己创建写入以下内容[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn timeout 120配置完成后可以用pip config list验证是否生效。这时候再执行pip install你会发现所有依赖包都会优先从清华源下载速度肉眼可见地提升。trusted-host这一项很多人会忽略。早期版本的 pip 对于非 HTTPS 或者证书有问题的源会直接拒绝虽然清华源本身是 HTTPS但加上这一句可以避免一些本地网络环境导致的证书校验异常。2.2 临时指定源与常用参数除了清华源有时候还需要临时换用其他源比如中科大、阿里云的 PyPI 镜像。不需要改配置一行命令搞定pip install flask -i https://mirrors.aliyun.com/pypi/simple/实际使用中还有几个参数非常实用--timeout用来调整超时时间--retries控制重试次数。如果网络状况不稳定可以组合使用pip install torch -i https://pypi.tuna.tsinghua.edu.cn/simple --timeout 60 --retries 5另外如果之前下载到一半的*.whl文件残留导致安装报错可以加上--no-cache-dir强制不走缓存重新下载或者用pip cache purge清空整个缓存目录。这个问题在安装大体积的 PyTorch 时尤其常见。2.3 pip 换源后的下载行为变化换源之后有个非常直观的变化依赖解析也变快了。因为 pip 在安装一个包时需要先去索引源拉取所有候选版本的元数据官方源经常在这一步就卡住。清华源对 PyPI 的元数据做了完整同步pip install时的网络交互延迟大大降低。我自己的实测经验默认源安装 PyTorch 及全套依赖耗时基本在十分钟以上还经常超时切到清华源后同样的机器和网络三分钟左右搞定。如果你的网络环境本身国际出口带宽就很好区别可能不明显但只要下载速度超过 1MB/s说明换源生效了。3. conda 换源别把清华源当成 conda 的万能药3.1 .condarc 配置文件的正确写法conda 的换源比 pip 复杂一点。直接执行以下命令添加清华源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 --set show_channel_urls yes执行后会自动在用户目录下生成或修改~/.condarc文件。也可以手动编辑这个文件常见写法是channels: - defaults - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ show_channel_urls: true配置完成后执行conda clean -i清除索引缓存下次conda install就会走清华源。很多人配置完发现速度没变化多半是忘了清缓存。这里有一个值得注意的点清华镜像的 Anaconda 仓库并不会同步所有 channel 渠道的全部内容pkgs/main和pkgs/free是完整同步的但某些 cloud 渠道的包同步频率和完整性都有限。所以如果遇到PackagesNotFoundError先判断是源里确实没有这个包还是你的 channel 配置有问题。3.2 为什么 conda install pytorch 经常装不上这是热词搜索里出现率极高的问题我在这里重点说透。很多人配好清华源之后执行conda install pytorch torchvision torchaudio -c pytorch发现还是从官方源下载速度依旧很慢或者直接报 404。原因是-c pytorch这个参数明确指定了从 PyTorch 官方 channel 下载此时清华源配置被完全绕过了。而清华镜像对 PyTorch 这个 cloud channel 的同步一直不稳定很多版本不完整所以最好不要指望用清华源 conda 来下载 PyTorch 的 GPU 版本。那 conda 装 PyTorch 的正确姿势是什么如果你愿意等直接去掉-c pytorch让 conda 从 defaults 渠道解析有些版本的 defaults 里有 pytorch 相关的包但版本通常落后更推荐的做法是直接用 pip 从清华源装 PyTorch下一节我会重点讲。3.3 conda 环境相关activate 报错与目录迁移热词里有一条condaerror: run conda init before conda activate这基本是新手标配。原因很简单conda 的命令行初始化脚本没有写入你的 shell 配置。Linux 下执行一次conda init bash然后重新打开终端conda activate就能正常使用了。Windows 下如果用的是 PowerShell执行conda init powershell再以管理员权限重启终端即可。另外很多人会遇到 conda 目录迁移的问题。比如 Anaconda 默认装在 C 盘用久了想挪到 D 盘直接剪切整个目录大概率会导致环境失效因为 conda 内部所有环境的路径都是绝对路径写死的。相对稳妥的方案是用conda env export environment.yml导出环境列表在新位置重新安装 conda 后用conda env create -f environment.yml重建环境。如果迁移的场景特别复杂可以考虑用conda-pack工具它能把环境打包成压缩文件再解压到新路径比手动改配置文件靠谱得多。4. PyTorch 安装实操一份能直接抄作业的流程4.1 先创建独立环境别污染系统 Python装 PyTorch 之前先创建一个干净的 conda 虚拟环境这是最重要的职业习惯。系统自带的 Python 往往有各种第三方包的版本依赖直接往里装 PyTorch轻则未来某个包升级时冲突重则直接把系统环境搞崩。创建环境的命令conda create -n torch python3.9 conda activate torchPython 版本的选择上PyTorch 官方对新版本的支持有滞后性目前选择 3.9 到 3.12 都比较稳妥不要一上来就用最新版 Python很可能会遇到某些依赖包还没有对应 wheel 的问题。环境创建好之后顺手把 pip 指向清华源参考第 2 节后面所有安装都会顺畅很多。很多人忽略这一步结果 PyTorch 本体装好了但一堆依赖比如 numpy、pillow、typing-extensions 卡在半路上。4.2 pip 路线安装 PyTorchGPU 版怎么选 CUDA现在直接用清华源从 PyPI 安装 PyTorchpip install torch torchvision torchaudio没有指定任何 CUDA 版本默认会从 PyPI 拉取适用当前系统的版本。这里有一个很多人没搞清楚的关键点在 Linux 上PyPI 发布的 PyTorch wheel 默认就内置了 CUDA runtime也就是说只要你的机器有 NVIDIA 显卡和足够新的驱动装完直接就能用 GPU不需要单独装一套完整的 CUDA Toolkit。Windows 上默认 wheel 是 CPU 版本想用 GPU 需要额外操作具体可以到 PyTorch 官网获取对应命令。如果你想明确指定某个 CUDA 版本可以走官方索引pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118这个命令走的是官方源下载速度取决于你的网络。实际操作经验是先评估自己的网络情况如果确实很慢可以考虑用下载工具把 wheel 文件拉到本地再用pip install 本地路径安装。不过这样必须手动把所有依赖也下载齐全比较麻烦还不如直接用清华源从 PyPI 装默认版本。4.3 conda 路线安装 PyTorch 的取舍也有不少人习惯用 conda 安装 PyTorch因为 conda 会自动处理 CUDA 相关的库和驱动的兼容性问题。如果你要用 conda 装我建议不要指定-c pytorch让 conda 自己解析 channel 优先级。前提是你在.condarc里配置好了清华源。conda install pytorch torchvision torchaudio cpuonly这个命令可以解决纯 CPU 版本的安装。如果要 GPU 版本且你的 conda 源能解析到执行conda install pytorch torchvision torchaudio即可。不过说实话在清华源 conda 的组合下装 GPU 版 PyTorch成功率并不稳定。我曾经在一台机器上试过conda 解析了十分钟后提示找不到匹配版本最后换回 pip 路线几分钟装完。我的建议是PyTorch 的安装优先走 pip因为 PyPI 上的 wheel 非常全、版本更新及时清华源同步也完整conda 适合管理 Python 环境和基础科学计算包比如安装 numpy、scipy、pandas 这类依赖关系复杂的包。环境管理用 conda包安装用 pip两者搭档效率最高。4.4 装机后验证确定 PyTorch 真的用上了 GPU装完之后不要着急写模型先验证一下环境是否真的可用。在 Python 里执行import torch print(torch.__version__) print(torch.version.cuda) print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))如果torch.cuda.is_available()返回False基本可以确定是 CUDA 版本和显卡驱动不匹配或者你装到 CPU 版本。注意torch.version.cuda显示的是 PyTorch 内置的 CUDA runtime 版本不需要和你系统里nvcc -V显示完全一致驱动版本只要不低于它要求的最低版本即可。上面这几行验证代码承载了一个重要的概念下一节我会展开讲PyTorch 自带的 CUDA runtime 和系统级 CUDA 安装其实是两回事。5. CUDA 相关坑装不上、版本对不上、文件损坏5.1 分清 driver、toolkit、PyTorch 内置 CUDA runtime很多人一上来就研究 CUDA 安装结果被各种概念绕晕。先理清楚三者的关系NVIDIA 显卡驱动Driver操作系统层面控制 GPU 的基础软件nvidia-smi查到的 CUDA Version 指的是驱动支持的最高 CUDA 版本。CUDA Toolkit完整的 CUDA 开发套件包含编译器 nvcc、各类库文件主要给开发原生 CUDA 程序的人用。PyTorch 内置 CUDA runtime打包在 wheel 里的运行库让 PyTorch 在不需要完整 Toolkit 的情况下也能调用 GPU 计算。对大多数只用 PyTorch 训练模型的场景只需要满足一个条件显卡驱动足够新、支持 PyTorch 对应的 CUDA 版本。系统里装不装 CUDA Toolkit 都不影响 PyTorch 跑 GPU。这也是为什么我用清华源从 PyPI 装完 PyTorch 直接就能用 GPU 的原因。nvidia-smi显示的 CUDA 版本如果高于 PyTorch 指定的版本通常没问题因为驱动向后兼容。比如驱动显示 CUDA 12.4跑 PyTorch 的 cu118 版本完全没问题。5.2 Ubuntu 上安装 CUDA 的常见失败与排查热词里有一条非常典型ubuntu cuda安装指令安装不了。这不是个例几乎所有人都遇到过。最常见的原因有这几个第一gzip: stdin: invalid compressed>export PATH/usr/local/cuda-11.8/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH建议把不同版本的切换写成一个 shell 脚本比如switch_cuda.sh参数传 11.8 或 12.1避免每次都手敲一大串命令。不过我还是要强调如果只是用 PyTorch多版本 Toolkit 的意义不大因为 PyTorch wheel 自带运行时环境你只需要保证驱动够新不需要关心系统里装没装 CUDA。5.4 PyTorch 版本与 CUDA 版本匹配速查热词里有一条cuda version: 13.0 需要安装ytorch的版本这背后是对版本匹配逻辑的误解。PyTorch 不会自动适配你系统里的任何 CUDA 版本你要做的是先确认驱动支持的 CUDA 最高版本nvidia-smi右上角然后选择等于或低于它的 PyTorch CUDA 版本。截至我写这篇内容的经验PyTorch 主流版本对应的 CUDA 支持范围大致是PyTorch 版本支持的 CUDA 版本PyTorch 2.0 - 2.3cu117 / cu118 / cu121PyTorch 2.4 - 2.7cu118 / cu124 / cu126较新版本cu124 / cu126 / cu128 及更高如果驱动显示 CUDA 13.0说明驱动非常新向下兼容所有旧版本直接用 cu118 或 cu124 都没问题。反过来如果你的驱动版本太老最高只支持 CUDA 11.8强行安装 cu124 会报No CUDA driver之类的错误这时候优先更新驱动而不是换旧版 PyTorch。6. 常见问题速查表与最后一点建议6.1 高频报错速查表把搜索热词里常见的报错和排查思路整理成一张表方便大家直接对照处理报错或问题主要原因解决办法pip 无法识别不是 cmdlet、函数或命令Windows 下 Python/Scripts 目录未加入 PATH重装 Python 时勾选 Add to PATH或手动添加环境变量conda activate 报错 run conda initconda 初始化脚本未写入 shell 配置执行conda init bashWindows 用conda init powershell后重启终端gzip: stdin: invalid compressed dataCUDA 安装包下载损坏重新下载并校验 SHA256确保文件完整再安装command pip install ultralytics.nn.modules.conv returned non-zero exitpip 依赖解析或包源访问异常升级 pippip install -U pip清理缓存重试必要时换源PackagesNotFoundErrorcondachannel 中没有该包或源不同步不完整检查 channel 配置更换官方源或改用 pip 安装清华源安装 PyTorch 失败试图用清华源 conda channel 装 PyTorch改用 pip 从 PyPI 清华源安装或直接用官方 index-urlComfyUI-Manager 安装失败依赖版本冲突或旧缓存更新 ComfyUI 本体清 pip 缓存后重试必要时用--enable-man相关参数这张表里的大部分问题我在实操中都遇过。有一个规律可以分享大部分安装报错都是缓存和路径问题最笨但最有效的方法就是创建一个全新环境重新来一遍。6.2 清华镜像源使用中的三个小提醒第一镜像源偶尔也会有同步延迟。如果你发现某个包在官方源已经发布了新版本但清华源还搜不到一般等几个小时就同步了。遇到特别急的情况可以临时用官方源装一次不要反复换源浪费时间。第二配置了多个源之后pip 和 conda 的优先级会变得混乱。建议 pip 就固定用清华源conda 也只保留一到两个 channel。我在一台家用机器上因为配置太多曾经出现过 conda 解析依赖时反复切换源、速度反而变慢的情况。第三虚拟机或者内网环境下镜像源有时候也会超时这时候优先检查是不是公司网络限制了外部访问而不是镜像源本身的问题。遇到 HTTPS 证书报错先确认系统时间是不是正常时间不对会导致证书校验失败。6.3 我在实际使用中的一点体会用清华镜像源这么多年最大的体会是它解决的是下载速度这个最简单的问题但很多人的安装失败并不是速度问题而是对 PyTorch、CUDA、conda 之间的关系理解不到位。先把工具链的逻辑理顺——conda 管环境pip 管 Python 包显卡驱动管硬件PyTorch 自带 CUDA runtime——再配合清华源的速度加持整个深度学习环境搭建就会变得非常顺滑。每到一个新机器工作我都是先conda create -n torch python3.9然后配上清华源接着pip install torch torchvision torchaudio十分钟不到环境就好了。这套流程跑了很多遍基本没有翻过车。