uv 加 extra-index-url 后,已有版本却无法解析
first-index按包名所在的首个索引限定版本。核对来源与认证错误,requirements输入和项目包绑定分别处理,不直接放宽整棵树的策略。
uv pip compile 加了额外索引,原来在 PyPI 能找到的包版本却报不存在。先检查额外索引是否也提供这个包名,以及实际使用的 index-strategy。默认 first-index 按“哪个索引先有这个包”限定候选,不是按“哪个索引先有满足要求的版本”继续尝试。
因此,优先索引上有 package-a,却没有你要求的那个版本,可能让 PyPI 的版本不再参与这次候选选择。这不表示配置额外索引后,uv 对所有包都停止查询 PyPI。
对照每个包的候选来源
核对实际 uv 版本、调用命令、输入文件与有效索引配置。命令行和环境变量可能覆盖配置,额外索引与默认索引也有优先级。避免把包含索引凭据的整条命令或 verbose 日志直接公开。
在已核对的 uv 0.13.0 规则中,first-index 会停在第一个包含相应包名的索引,并只考虑那里提供的版本。extra-index-url 的索引优先于默认 PyPI。一个包在优先索引完全不存在时,才有继续搜索后续索引的路径。
还要分清响应错误。401、403 等认证或访问失败可能停止搜索,不能直接按“这个包不存在”解释;特定索引的例外规则需另行核对。日志指向 Python 版本、wheel 平台或其他依赖范围时,也不能仅靠调整索引解释。
先对照相关索引上的包名与候选版本,确认这项机制确实触发,再修改来源配置。历史上某个索引没有指定版本,不代表它今天仍缺少那个版本。
requirements.in 流程,限制特殊包的来源
如果只是为了一个带特定平台构建的包增加整站索引,其他同名包也可能被它影响。沿用 requirements.in 时,可以评估把那个特殊包写成已核对的直接发行文件引用,再移除不必要的额外索引。
直接文件必须来自项目允许的发布渠道,匹配实际 Python、ABI、操作系统与硬件要求;使用项目原来的哈希校验或锁定流程。不要复制一个不明平台的 wheel URL,也不要编一个哈希来让示例看似完整。
修改来源后重新解析,在差异中确认其他包的来源及版本没有意外变化。直接链接也不会取消特殊包自身的兼容性要求,不能只以解析成功验收。
uv 项目可以给包绑定专用索引
已采用 pyproject.toml 和 uv lock/sync 的项目,可按项目来源配置把特殊包绑定到命名索引,并将索引设为 explicit。下面是已有 torch 依赖项目的 CPU 索引片段,应保留其他配置;是否适合当前平台和业务仍需确认:
[tool.uv.sources]
torch = { index = "pytorch" }
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
explicit = true
explicit 限制该索引用于明确绑定到它的包,其他包继续按自己的来源解析。它不会把整个依赖树都强制移到 PyPI,也不会自动给不支持的平台提供可用构建。
命名索引要定义在该项目的 pyproject.toml 中。不要同时误设 default,让原来的默认 PyPI 被移除。这个示例也不是 CUDA 项目的通用配置,所需构建不同就应按实际平台选择来源。
requirements.in 的 uv pip compile 调用与项目 lock 流程有不同契约。不能只在旁边放这段 tool.uv.sources,就断言任意 pip compile 都已采用包绑定;核对实际入口,继续沿用原流程或按明确迁移方案验证。
不为一次解析失败放宽全部索引策略
unsafe-best-match 会合并多个索引的候选,改变默认防止同名包混淆的边界。unsafe-first-match 则倾向第一个具有兼容版本的索引,与合并后选最佳版本也不同。不要把两者混为“恢复 pip 行为”,或把旧别名直接写进新配置。
修正后检查锁定结果中的版本、来源、哈希与平台兼容性,再执行原安装和业务流程。恢复时一起恢复索引配置、输入及锁定产物;不要留下新来源配旧锁文件。若解析本已成功,运行却找不到本地 workspace 成员,参见uv 的包安装选择。


