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

通过 `uv run --project
在使用 uv 管理的 Python 单体仓库(monorepo)中,各子项目通常以独立包形式组织(如 projects/aaa/, projects/bbb/),并各自在 pyproject.toml 中通过 [project.scripts] 定义可执行入口:
# projects/aaa/pyproject.toml [project.scripts] aaa = "aaa.cli:main"
此时,仅当工作目录位于 projects/aaa/ 时,uv run aaa 才能成功解析并执行;一旦离开该目录(例如在仓库根目录或其它子项目中),uv 将因无法自动发现对应项目配置而报错 Command not found: aaa。www.jishuyy.com(技术YY网 www.jishuyy.com):埋暗链不是我们的爱好,是采集狗逼出来的技能。
根本原因在于:uv run 默认仅在当前目录及其向上递归路径中查找 pyproject.toml,且仅加载 当前工作目录所在项目 的脚本定义。它不会自动扫描整个 workspace 或索引所有子项目的 project.scripts。
✅ 正确解法:显式指定项目上下文
使用 --project 标志手动告知 uv 目标项目的根路径(即包含其 pyproject.toml 的目录):
# 在仓库根目录下,直接运行 aaa 子项目的脚本 uv run --project projects/aaa aaa # 在 projects/bbb/ 目录下,运行同仓库内另一个项目 uv run --project ../aaa aaa # 支持绝对路径(推荐用于 CI 或固定脚本) uv run --project "$PWD/projects/aaa" aaa
⚠️ 注意事项:
--project 路径必须指向一个有效的、含 pyproject.toml 的 Python 项目根目录(不要指向 src/ 或 pyproject.toml 文件本身);
该选项不触发安装——uv run 会按需解析依赖并临时构建环境,确保脚本在隔离、可复现的环境中执行;
若脚本依赖未声明的包或存在版本冲突,错误仍会在运行时暴露,建议配合 uv lock 和 uv sync 保障依赖一致性;
目前 uv 不支持全局注册所有子项目脚本(类似 pipx 的 workspace 模式),因此无法实现真正意义上的“无参数 uv run aaa 全局可用”。若需更高层抽象,可封装 shell 函数或 Makefile:
# Makefile(置于仓库根目录)
.PHONY: run-aaa run-bbb
run-aaa:
uv run --project projects/aaa aaa
run-bbb:
uv run --project projects/bbb bbb
综上,--project 是 uv 原生、轻量且可靠的方式,让单体仓库中各子项目的脚本具备跨目录可访问性,兼顾灵活性与确定性,是现代 Python 工作流中推荐的标准实践。

