前言默认情况下pip下载第三方Python库会访问国外PyPI官方服务器国内服务器、本地电脑经常出现下载缓慢、超时失败、连接中断等问题。通过切换国内镜像源可以大幅提升下载速度解决ReadTimeoutError、连接超时等常见报错。国内主流稳定镜像源清单清华大学源推荐同步及时https://pypi.tuna.tsinghua.edu.cn/simple阿里云源https://mirrors.aliyun.com/pypi/simple中国科学技术大学源https://pypi.mirrors.ustc.edu.cn/simple本文覆盖临时使用源、全局永久配置、多版本Python区分配置、配置文件手动编写、清除缓存、常见问题。同时兼容 Windows / Linux / MacOS。一、临时使用镜像源单次生效适合临时加速安装只对当前这一条安装命令生效不需要修改任何配置文件。语法格式pipinstall包名-i镜像地址示例使用清华源安装requestspipinstallrequests-ihttps://pypi.tuna.tsinghua.edu.cn/simple针对你服务器多版本Python场景python39 / python312# Python3.12pip312installrequests-ihttps://pypi.tuna.tsinghua.edu.cn/simple# Python3.9pip39installrequests-ihttps://pypi.tuna.tsinghua.edu.cn/simple二、全局永久配置pip国内源推荐配置完成后所有pip安装命令默认走国内镜像无需每次加-i参数。方式1命令一键配置最简单pip 10.0 支持Linux / MacOS# 配置清华源pip configsetglobal.index-url https://pypi.tuna.tsinghua.edu.cn/simple多Python版本注意如果你服务器存在多个Python需要分别执行对应pip命令单独配置pip312 configsetglobal.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip39 configsetglobal.index-url https://pypi.tuna.tsinghua.edu.cn/simpleWindows CMD/PowerShellpip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple方式2手动创建配置文件兼容所有低版本pipLinux / MacOSpip配置文件路径~/.pip/pip.conf创建目录mkdir-p~/.pip写入配置cat~/.pip/pip.confEOF [global] index-url https://pypi.tuna.tsinghua.edu.cn/simple [install] trusted-host pypi.tuna.tsinghua.edu.cn EOFtrusted-host作用关闭https证书校验避免部分环境报ssl信任错误。Windows系统在用户目录下创建pip文件夹新建pip.ini路径C:\Users\你的用户名\pip\pip.ini内容[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple [install] trusted-host pypi.tuna.tsinghua.edu.cn三、查看当前pip源配置确认配置是否生效pip config list# 多版本pip312 config list pip39 config list输出包含index-url地址代表配置成功。四、恢复官方默认源如果后续需要切回原始PyPI源执行清除命令pip configunsetglobal.index-url# 指定版本pip312 configunsetglobal.index-url或者直接删除配置文件rm-rf~/.pip/pip.conf五、高级可选配置优化下载体验扩展配置写入pip.conf/pip.ini增加超时时间、开启并发下载[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple timeout 120 [install] trusted-host pypi.tuna.tsinghua.edu.cn max-parallel-downloads 8参数说明timeout下载超时时间弱网络服务器建议调高max-parallel-downloads开启多包并行下载六、常见问题解决问题1配置源之后依然下载很慢清理pip缓存pip cache purge检查服务器出口网络部分云厂商内网环境对外部镜像限速可以切换阿里云源测试问题2报错Could not fetch URL xxx: There was a problem confirming the ssl certificate解决方案配置文件添加trusted-host上文模板已自带或者安装命令追加参数--trusted-host pypi.tuna.tsinghua.edu.cn问题3多版本Python只有一个pip生效核心原因不同Python拥有独立pip必须分别使用 pip39 / pip312 各自执行config命令不能只配置系统pip。问题4虚拟环境不继承全局源正常现象虚拟环境可以进入环境内部再次执行配置命令或者把pip.conf放置到项目内。七、备选镜像地址源失效时切换清华源https://pypi.tuna.tsinghua.edu.cn/simple阿里云https://mirrors.aliyun.com/pypi/simple中科大源https://pypi.mirrors.ustc.edu.cn/simple总结临时加速安装命令追加-i 镜像地址长期使用pip config一键设置全局源操作最简单Linux多Python环境3.9 /3.12务必单独配置对应pip遇到ssl报错不要忘记配置 trusted-host建议编译安装完Python3.12.10之后立刻执行pip312 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple避免后续安装第三方库出现超时问题。
