如何配置uv使uv sync自动拉取Git依赖的最新提交？

核心问题原因 #

uv默认会缓存Git依赖的提交哈希，即使依赖声明跟踪分支，也不会自动检测远程仓库的最新提交，需要显式触发刷新或配置自动检查逻辑。

可行解决方案 #

1. 强制刷新Git依赖（临时快速方法）

直接在uv sync时添加--refresh参数，强制uv重新拉取仓库最新提交并对比更新：

uv sync --refresh

2. 确保依赖跟踪分支而非固定提交哈希

检查主项目的pyproject.toml，确保依赖项明确跟踪目标分支，避免uv锁定到旧提交：

dependencies = [
  "quantstats @ git+https://github.com/PowerInsight/quantstats.git@main",
]

修改后配合uv sync --refresh即可拉取分支最新代码。

3. 配置uv自动刷新特定Git依赖

在主项目pyproject.toml中添加专属配置，让uv每次sync时自动检查该仓库的最新提交：

[tool.uv.dependencies]
quantstats = { git = "https://github.com/PowerInsight/quantstats.git", branch = "main", refresh = true }

配置完成后，直接运行uv sync就会自动拉取该依赖的最新提交并更新虚拟环境。

4. 清理uv Git缓存（极端场景）

如果缓存残留导致更新失效，可清理uv的Git缓存后重新同步：

uv cache clean --git
uv sync

为什么之前的配置未生效 #

• cache-keys配置用于自定义缓存键，但uv默认已基于Git提交哈希缓存，该配置无法触发自动刷新；
• reinstall-package仅强制重装，但如果依赖被锁定到旧提交哈希，重装仍会使用旧版本，需结合分支跟踪和刷新逻辑。

内容的提问来源于stack exchange，提问作者EtienneT