pip 永久配置清华镜像源：一行命令解决下载龟速与 ReadTimeout 错误
Python 开发中，pip 默认从 pypi.org 下载依赖，国内网络经常出现几十 KB/s 的速度，甚至 ReadTimeoutError、ConnectionError 报错。每次手动加 -i 参数虽然能临时解决，但不够持久。更高效的做法是全局配置镜像源，一次设置，后续所有 pip install 和 pip install -r requirements.txt 自动走国内镜像。本文以清华大学开源软件镜像站（Tuna）为例，提供最简洁的永久配置方法，同时覆盖验证、恢复官方源、虚拟环境特殊处理以及常见问题的排查。
1. 为什么选择清华镜像？
地址：https://pypi.tuna.tsinghua.edu.cn/simple
同步频率：每 5 分钟与官方源同步一次
特点：稳定、高速、永久免费，实测下载 numpy 从 45 KB/s（多次重试）提升到 8.2 MB/s，pytorch 从经常超时变为稳定 12 MB/s，50 个包的 requirements.txt 从 5~10 分钟缩短到 30 秒内。
2. 一键永久配置（推荐，全平台通用）
在终端（CMD、PowerShell、Bash）中依次执行以下两条命令：
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 验证，输出应包含上述两条设置。此后无论执行 pip install 包名 还是 pip install -r requirements.txt，都会自动走清华镜像，无需再加 -i 参数。
3. 备选方案：手动编辑配置文件
如果命令行方式不可用，也可以直接编辑 pip 配置文件：
Windows：%APPDATA%\pip\pip.ini
Linux/macOS：~/.config/pip/pip.conf 或 ~/.pip/pip.conf
在文件中添加以下内容：
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
保存后即生效。
4. 如何切回官方默认源？
如果需要恢复官方源（例如某些包因镜像同步延迟而找不到最新版本），执行：
pip config unset global.index-url
pip config unset global.trusted-host
完成后 pip 恢复使用官方源 https://pypi.org/simple。
5. 其他国内镜像源备选
若清华源暂时不可用，可替换为以下任意一个，配置方法完全相同（替换 URL 即可）：
阿里云：https://mirrors.aliyun.com/pypi/simple
豆瓣：https://pypi.douban.com/simple
中科大：https://pypi.mirrors.ustc.edu.cn/simple
华为云：https://repo.huaweicloud.com/repository/pypi/simple
6. 虚拟环境中的换源注意事项
pip 配置是全局生效的，因此使用 venv 或 conda 创建的虚拟环境也会自动沿用全局设置。如果希望仅对当前项目生效，可以在项目根目录下创建 pip.conf / pip.ini（内容同上），或者在 pip install 时临时指定：
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple 包名
7. 常见问题 FAQ
Q：配置后依然走官方源？
A：检查项目根目录下是否有 .pip 文件夹下的配置文件，它会覆盖全局设置。也可以执行 pip install --no-cache-dir 包名 禁用缓存后重试。
Q：公司内网限制了镜像源？
A：可以尝试使用 HTTP 协议（将 https 改为 http），或者在内部搭建私有 PyPI 代理。
Q：conda 用户如何换源？
A：conda 换源需修改 .condarc 文件，命令如下：
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --set show_channel_urls yes
附：常用命令速查表
全局配置清华源：
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
恢复官方源：
pip config unset global.index-url
pip config unset global.trusted-host
配置成功后，pip 下载速度可提升 10~50 倍，且不再需要手动携带 -i 参数。推荐优先使用清华镜像，稳定且同步快。
Re: pip 永久配置清华镜像源：一行命令解决下载龟速与 ReadTimeout 错误
楼主这个总结很实用！之前老是遇上 ReadTimeout，加了 -i 也只能管一次，现在全局配好省心多了。另外想请教下：如果项目中已有 requirements.txt，配置后首次安装会不会因为缓存问题还是走官方源？Re: pip 永久配置清华镜像源：一行命令解决下载龟速与 ReadTimeout 错误
谢谢分享，非常详细实用的教程！之前每次装包都要手动加 `-i` 确实挺烦的，用你这两行命令全局配置好，以后省事多了。实测清华源确实稳定，下载速度提升非常明显。另外备选源和回退官方源的方法也写清楚了，对新手很友好。收藏了！Re: pip 永久配置清华镜像源：一行命令解决下载龟速与 ReadTimeout 错误
这篇帖子非常实用，感谢楼主分享这么详细的配置方案！之前经常遇到pip下载超时或速度缓慢的问题，每次都要手动加`-i`参数确实麻烦。按照你提供的一键配置命令，几秒钟就设置好了，后面再安装依赖明显快了很多，验证配置也一目了然。另外，帖子中关于虚拟环境、恢复官方源以及其他备选镜像的说明也考虑得很周全，对新手非常友好。建议置顶或加精，应该能帮到很多被下载速度困扰的Python开发者。
页:
[1]