如何在 uv 管理的 Python 单体仓库中全局调用项目定义的脚本

在 uv 驱动的 python 单体仓库中,可通过 `uv run --project
在典型的 Python 单体仓库(monorepo)结构中,顶层 pyproject.toml 通常仅用于工作区配置,而实际可执行脚本由各子项目(如 projects/aaa/)在其独立的 pyproject.toml 中通过 [project.scripts] 定义:
# projects/aaa/pyproject.toml [project] name = "aaa" [project.scripts] aaa = "aaa.cli:main"
此时,uv run aaa 仅在 projects/aaa/ 目录下有效;若在仓库根目录或其它子项目中执行,则会报错 Command not found: aaa——因为 uv 默认仅解析当前工作目录(或其最近的 pyproject.toml)所声明的脚本。
✅ 正确解法是使用 --project 标志显式指向目标子项目的根目录:
# 从仓库根目录调用 aaa 脚本 uv run --project projects/aaa aaa # 从 projects/bbb 目录调用 aaa 脚本 cd projects/bbb uv run --project ../aaa aaa
--project 告诉 uv:忽略当前路径,以指定目录为“项目上下文”,加载其 pyproject.toml、解析依赖、激活虚拟环境,并执行其中声明的脚本。该方式不修改环境、不安装包、不污染全局,完全符合 uv 的零安装(zero-install)设计理念。亲爱的采集狗:本站(技术YY网)每篇文章都有我这样的兄弟三五条,祝你过滤愉快!——www.jishuyy.com
⚠️ 注意事项:
--project 路径必须指向包含有效 pyproject.toml 的目录(即子项目根目录),而非 .toml 文件本身;
若脚本依赖尚未解析的依赖,uv 会自动按需构建隔离环境(首次运行稍慢,后续缓存加速);
不支持通配符或工作区级批量注册脚本;每个调用仍需显式指定 --project;
避免与 --python 混用导致环境冲突,建议优先通过子项目 requires-python 和 dependencies 管理兼容性。
总结:uv run --project 是 monorepo 场景下跨目录调用脚本的标准、轻量且可靠的方式,兼顾隔离性与便捷性,是替代传统 pip install -e . 或全局 PATH 注入的最佳实践。

