临时增加超时#

1
python -m pip install pandas --timeout 120 --retries 5

如果只是网络慢，增加 timeout 和 retries 就能解决。

使用镜像源#

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

镜像源适合下载慢的情况。但如果是包版本不存在，换源也没用。

先升级 pip#

1
python -m pip install --upgrade pip

较旧 pip 可能无法正确处理新格式 wheel，升级后再安装更稳。

离线或服务器环境#

服务器不能联网时，可以在本地下载 wheel，再上传安装。

1
python -m pip download -r requirements.txt -d wheels
2
python -m pip install --no-index --find-links wheels -r requirements.txt

实战复盘#

把《pip 下载超时处理》写成可复用排查记录时，我会保留四类证据：原始现象、执行命令、关键输出、修复后的验证结果。少了其中任何一类，下次遇到类似问题都容易重新猜一遍。

排查类文章不要只写最终命令，还要写为什么先查这里。比如端口问题先看监听进程，Nginx 问题先分清 404 和 403，Python 环境问题先确认解释器路径。

如果修复动作有风险，例如杀进程、删文件、改服务配置，就应该写清回退方式。能恢复，才敢在服务器上操作。

最小验收样例#

验收《pip 下载超时处理》时，我会保留一条修复前命令和一条修复后命令。前者证明问题存在，后者证明问题已经消失，而不是只凭浏览器或终端感觉判断。

如果这篇文章涉及服务器操作，还要记录当前路径、用户、服务名和关键配置文件。排查记录越能还原现场，下次遇到同类问题越不需要重新摸索。

小结#

pip 超时先判断网络，再处理源和重试。安装失败时保留完整错误，比盲目换命令更有效。