uv pip安装报错“Request failed after 3 retries”主因是网络不稳定触发默认超时（15秒连接+60秒读取）与3次重试机制；解决需优先换国内镜像源、调大UV_HTTP_TIMEOUT至180秒，再视情禁用缓存验证。
uv pip 安装失败，八成不是 uv 本身的问题，而是网络不稳定触发了它的默认重试和超时机制。直接调大超时、换镜像、跳过缓存验证，比反复重试更有效。
为什么 uv pip install 会卡在 “Request failed after 3 retries”
这个错误不是随机出现的，它背后有明确的触发条件：uv 默认只给每个请求 15 秒连接 + 60 秒读取，且最多重试 3 次。当网络抖动、DNS 解析慢、或镜像源响应延迟超过 60 秒（比如下载 torch 或 scipy 这类大包时），就会直接报错退出，不等你手动干预。
- 它不像 pip 那样可能静默卡住几十秒再失败，uv 的失败是“果断但苛刻”的
- 错误信息里通常带
error: Request failed after 3 retries，而不是 SSL 错误或证书问题 - 同一命令在公司内网失败，回家 Wi-Fi 却成功——基本可锁定为本地网络质量或出口限制
临时生效：用环境变量覆盖默认超时与镜像
不用改配置文件，适合 CI/CD 或临时调试。关键参数就两个：UV_INDEX_URL 指定镜像源，UV_HTTP_TIMEOUT 延长读取等待时间。
- Linux/macOS 终端执行（立即生效，当前 shell 有效）：
export UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple/"export UV_HTTP_TIMEOUT="180" - Windows PowerShell 执行：
$env:UV_INDEX_URL="https://mirrors.aliyun.com/pypi/simple/"$env:UV_HTTP_TIMEOUT="180" -
UV_HTTP_TIMEOUT单位是秒，设为180表示单个包下载允许最长 3 分钟，对国内网络更友好 - 清华源和阿里云源都稳定，但阿里云对大包分块下载支持更好，遇到
torch类包可优先试阿里云
永久生效：写入 uv.toml 配置文件
PyCharm 或 VS Code 启动的终端也认这个配置，适合长期开发环境。注意路径和格式必须严格：
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
立即学习“Python免费学习笔记（深入）”；
- Windows 路径：
%APPDATA%\uv\uv.toml（即C:\Users\用户名\AppData\Roaming\uv\uv.toml） - macOS/Linux 路径：
~/.config/uv/uv.toml - 文件内容必须是 TOML 格式，且只保留一个
default = true的索引源：[[index]]<br>url = "https://pypi.tuna.tsinghua.edu.cn/simple/"<br>default = true
- 不要加注释行在
[[index]]上方，否则 uv 会静默忽略整个配置 - 改完后必须重启终端或 IDE，否则新配置不加载
进阶应对：禁用缓存验证避免“假失败”
有时失败并非因为下不下来，而是 uv 下载完后校验哈希时发现缓存文件损坏，就放弃重试直接报错。这种情况在磁盘 I/O 不稳或杀毒软件干扰时常见。
- 加
--no-cache强制跳过本地缓存，走纯下载流程：uv pip install --no-cache requests - 加
--refresh清掉可疑缓存并重新拉取元数据：uv pip install --refresh numpy - 二者不互斥，可组合使用：
uv pip install --no-cache --refresh -i https://pypi.tuna.tsinghua.edu.cn/simple/ pandas - 注意：
--no-cache会失去 uv 最快的优势，仅建议在确认是缓存污染导致失败时使用
真正麻烦的不是超时数字本身，而是 uv 默认不告诉你哪一步卡住了——它不会像 pip 那样打印“正在从 xxx 下载”，只会最后甩一句失败。所以排查时先换源、再调超时、最后怀疑缓存，顺序不能乱。否则你调了 300 秒超时，结果问题出在 DNS 解析上，白等三分钟。
