pip install 超时 / ReadTimeoutError:换国内镜像源一次解决

用 pip 装包最常见的报错:ReadTimeoutError、ConnectionError,或者进度条卡在下载。

报错现象

WARNING: Retrying (Retry(total=4, connect=None, read=None, ...)) ...
ReadTimeoutError: HTTPSConnectionPool(host='files.pythonhosted.org', port=443): Read timed out.

原因分析

• pip 默认从官方 PyPI(pypi.org)下载,国内网络直连不稳定
• 大包(如 torch、pandas)体积大,更容易超时

解决步骤

1. 临时指定镜像源

pip install pandas -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 永久配置镜像源(推荐)

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

国内常用镜像(任选其一):

镜像	地址
清华 TUNA	https://pypi.tuna.tsinghua.edu.cn/simple
阿里云	https://mirrors.aliyun.com/pypi/simple/
腾讯云	https://mirrors.cloud.tencent.com/pypi/simple
中科大	https://pypi.mirrors.ustc.edu.cn/simple

3. 还慢就加大超时

pip install pandas --default-timeout=120 -i https://pypi.tuna.tsinghua.edu.cn/simple

效果验证

• 下载速度明显提升,不再超时
• pip config list 能看到 index-url 已生效

核心经验:pip 慢先换源,别硬等。换完镜像源后,绝大多数超时问题一次解决。