pip install 超时因默认连接海外 PyPI 源延迟高，应改用国内镜像源（如清华 https://pypi.tuna.tsinghua.edu.cn/simple/），支持临时（-i 参数）或永久（配置 pip.ini/pip.conf）生效，并注意 trusted-host 与 URL 匹配、文件编码等细节。
为什么 pip install 总是超时或卡在 downloading 阶段
国内直接走官方 PyPI（https://pypi.org/simple/）下载包，常因网络抖动、DNS 解析慢或中间路由限制导致连接超时、重试频繁，甚至返回 ReadTimeoutError 或 ConnectionError。这不是你网络差，而是默认源物理距离远、无 CDN 加速。
解决思路不是换代理，而是把源换成国内高校或云厂商维护的镜像站，它们同步官方索引、提供 HTTPS 接口、带缓存和 CDN，响应快且稳定。
- 清华镜像：
https://pypi.tuna.tsinghua.edu.cn/simple/（推荐，同步及时，支持 IPv6） - 中科大镜像：
https://pypi.mirrors.ustc.edu.cn/simple/（稳定，但偶尔同步延迟几分钟） - 阿里云镜像：
https://mirrors.aliyun.com/pypi/simple/（适合企业内网环境）
临时生效：用 -i 参数指定镜像源
适合单次安装、CI 脚本或不想改全局配置的场景。加了 -i 就只对当前命令生效，不影响其他操作。
示例：
立即学习“Python免费学习笔记（深入）”；
pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple/
注意两点：
- 必须带
/simple/后缀，少写会报404 Not Found - 如果包有依赖且依赖包不在该镜像站（极少见），pip 会自动 fallback 到官方源——除非你加了
--trusted-host - 首次使用 HTTPS 镜像时可能提示证书警告，可追加
--trusted-host pypi.tuna.tsinghua.edu.cn消除（不建议长期忽略证书校验）
永久生效：修改 pip 配置文件
Windows 和 macOS/Linux 路径不同，但原理一致：让 pip 每次都读取这个配置，无需重复敲 -i。
Claw Code Suite (Python-Only Edition)
下载
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
配置文件路径：
- Windows：
%APPDATA%\pip\pip.ini（如C:\Users\Alice\pip\pip.ini） - macOS / Linux：
$HOME/.pip/pip.conf
创建目录和文件（若不存在），写入以下内容：
[global] index-url = https://pypi.tuna.tsinghua.edu.cn/simple/ trusted-host = pypi.tuna.tsinghua.edu.cn
关键点：
-
index-url是主源，只写一个；若想加备用源（fallback），得用extra-index-url，但多数人不需要 -
trusted-host必须与index-url的域名一致，否则 HTTPS 请求会失败 - 不要在 URL 末尾加斜杠以外的字符（比如
?format=xml），pip 不识别
验证是否生效 & 常见失效原因
运行 pip config list 可查看当前生效的配置项；更直接的是执行 pip install -v some-package，观察日志里实际请求的 URL 是否为镜像地址。
如果仍走官方源，常见原因：
- 配置文件路径写错（尤其 Windows 下容易误建在
pip目录同级） - 文件编码不是 UTF-8 无 BOM，导致 pip 读取失败（用记事本保存时选“UTF-8”而非“ANSI”）
- 存在多级配置冲突：项目级
pyproject.toml或setup.cfg中定义了index-url，会覆盖用户级配置 - 某些 IDE（如 PyCharm）自带 pip 环境，它可能读取自己的配置或虚拟环境内的 pip，需单独设置
镜像源本身不是万能加速器——如果包体积极大（如 torch CPU 版本），下载时间仍取决于你的带宽；而小包（requests、click）通常 1–2 秒内完成。
