使用 uv 安装 github 上的开源库,最直接的方法是在 pip install 命令中指定 git 仓库的 https 或 ssh url。例如运行 uv pip install git+https://github.com/user/repo.git 即可将代码克隆到本地并安装。如果需要安装特定的分支、标签或提交版本,可以在 url 后附加 @branch_name 或 @commit_hash 来锁定版本。此外,如果该库在项目中作为依赖存在,也可以直接在 pyproject.toml 文件的 [project.dependencies] 或 [project.optional-dependencies] 中添加对应的 git url 字符串,然后运行 uv sync 进行解析和安装。

如何安装特定分支或提交的代码
当需要安装非默认分支(如 dev)或特定历史版本的代码时,只需在 Git URL 后添加 @ 符号及对应的标识符。这种方式允许你精确控制安装的代码快照,避免因为上游仓库更新导致的行为不一致。对于开发者来说,这通常用于测试新功能或回退到已知稳定的旧版本。执行该操作时,uv 会像处理普通包一样处理这些引用,将其解析为具体的源代码并构建安装。

uv pip install git+https://github.com/psycopg/psycopg.git@v3.1.x
上述命令会安装 psycopg 仓库中符合 v3.1.x 标签的最新提交。如果希望安装某个具体的 commit hash,可以将 @v3.1.x 替换为 @a1b2c3d4。安装完成后,可以通过 uv pip show psycopg 查看已安装的版本信息,确认其指向了正确的 Git 引用。这种基于 URL 的安装方式不依赖于 PyPI,完全从源码构建,因此适用于尚未发布到包管理器的实验性代码。
如何在 pyproject.toml 中声明 Git 依赖
在项目管理中,将 Git 仓库作为依赖写入配置文件是更规范的做法。在 pyproject.toml 文件中,可以使用标准的 PEP 508 格式来描述 Git 依赖。具体做法是在依赖列表中直接写入完整的 Git URL 字符串。这种方法的好处是依赖关系被明确记录在项目配置中,其他协作者或 CI/CD 环境只需运行 uv sync 即可复现相同的环境。需要注意的是,Git URL 必须包含协议前缀(如 git+https://),且不能包含空格。
使用 GitHub Next 的 CI Doctor 工作流来监视 GitHub Actions 运行、拉取失败日志、追踪重复模式,并打开带有具体下一步操作的调查问题。这是供代理作为 CI 失败调查员使用的,而不是用于将 GitHub Agentic Workflows 列为产品。

[project]
name = "my-project"
version = "0.1.0"
dependencies = [
"requests",
"git+https://github.com/user/special-lib.git@main"
]
保存上述 pyproject.toml 后,运行 uv sync。uv 会识别出 special-lib 是一个 Git 依赖,自动克隆对应分支的代码,并在虚拟环境中安装它。与命令行安装相比,这种方式确保了依赖树的确定性。如果后续需要更新该库到最新状态,只需再次运行 uv sync,它会检查远程仓库是否有新的提交并相应更新。若需锁定版本以防意外更新,可结合 uv.lock 文件使用,该文件会记录当前解析出的确切 Git commit hash。
安装带有子目录的 Git 仓库
有些大型项目采用多包结构,即一个 Git 仓库中包含多个独立的 Python 包,分布在不同的子目录下。在这种情况下,直接使用完整的 Git URL 安装可能会失败,因为 uv 无法确定要安装哪个子包。解决这个问题的方法是使用 #subdirectory=path/to/subdir 后缀来指定具体的子目录路径。这使得 uv 能够正确定位到目标包的 pyproject.toml 或 setup.py 文件,从而完成安装。这对于使用 monorepo 架构的团队尤其有用,可以灵活地引用内部共享组件。
uv pip install "git+https://github.com/monorepo/project.git#subdirectory=libs/shared-lib"
该命令指示 uv 克隆整个仓库,但仅安装 libs/shared-lib 目录下的内容。安装成功后,该子包会被视为一个独立的依赖项加入虚拟环境。如果在 pyproject.toml 中声明,写法类似:shared-lib = { git = "https://github.com/monorepo/project.git", subdirectory = "libs/shared-lib" }。这种方式保持了仓库的完整性,同时实现了模块化的依赖管理。开发者应注意子目录路径的正确性,任何拼写错误都会导致安装失败。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!










