
通过 uv run --project 显式指定项目根目录,即可在单体仓库任意位置运行任一子项目的 project.script,无需切换路径或重复安装。
通过 `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。
根本原因在于:uv run 默认仅在当前目录及其向上递归路径中查找 pyproject.toml,且仅加载 当前工作目录所在项目 的脚本定义。它不会自动扫描整个 workspace 或索引所有子项目的 project.scripts。
当现有的脚本或服务需要将作用域化的仓库工作委托给 Claude Code 并以编程方式消费结构化响应时,请使用 Claude Agent SDK for Python。
✅ 正确解法:显式指定项目上下文
使用 --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
⚠️ 注意事项:
立即学习“Python免费学习笔记(深入)”;
-
--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 工作流中推荐的标准实践。


















