DEBUG.WIKI
京东云;让 AI 进入真实业务;零售 · 物流 · 客服 · 硬件;查看方案 →
ZgoCloud:多地区部署,按需选节点;日本、美国、香港、德国
Evoxt;最高 6.0GHz CPU;高频云服务器 · 免费每周备份;查看配置 →

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 的包安装选择。