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 就只对当前命令生效，不影响其他操作。

示例：

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 秒内完成。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！