
通过 uv run --project 显式指定项目根目录,即可在单体仓库任意位置运行任一子项目的可执行脚本,无需切换工作目录或重复安装。
通过 uv run --project <path></path> 显式指定项目根目录,即可在单体仓库任意位置运行任一子项目的可执行脚本,无需切换工作目录或重复安装。
在使用 uv 管理的 Python 单体仓库(monorepo)中,各子项目通常位于独立目录(如 projects/aaa/、projects/bbb/),并各自拥有 pyproject.toml 和 [project.scripts] 定义(例如 aaa = "aaa.cli:main")。虽然在子项目目录内可直接执行 uv run aaa,但该命令默认仅在当前目录及其父级中搜索 pyproject.toml,因此在仓库顶层或其他子项目目录下会报错 Script 'aaa' not found。
解决方法是使用 --project 标志显式声明目标项目路径:
# 从仓库根目录调用 projects/aaa 中定义的脚本 uv run --project projects/aaa aaa # 从 projects/bbb 目录下调用同仓库内另一个项目脚本 cd projects/bbb uv run --project ../aaa aaa # 支持相对路径、绝对路径,甚至符号链接路径 uv run --project /full/path/to/projects/aaa aaa
✅ 关键要点:
当现有的脚本或服务需要将作用域化的仓库工作委托给 Claude Code 并以编程方式消费结构化响应时,请使用 Claude Agent SDK for Python。
-
--project必须指向包含pyproject.toml的项目根目录(即定义[project.scripts]的那个目录),而非包源码目录; -
uv run会自动解析该目录下的pyproject.toml,加载其依赖与脚本入口,行为等价于cd <project-dir> && uv run <script></script></project-dir>; - 无需预先
uv sync或uv install,uv run会按需构建隔离环境并执行; - 可与其他标志组合使用,如
--python 3.12指定解释器版本,或--with pytest临时添加依赖。
⚠️ 注意事项:
立即学习“Python免费学习笔记(深入)”;
- 不要将
--project误设为包名(如aaa)或模块路径(如aaa.cli)——这会导致uv无法定位配置文件; - 若脚本依赖未在
project.dependencies中声明的开发依赖(如pytest),需通过--with显式注入,或改用[project.optional-dependencies]并启用对应组; - 在 CI/CD 或自动化脚本中推荐使用绝对路径或基于
$PWD的可靠相对路径,避免因执行上下文变化导致路径失效。
综上,--project 是 uv 原生支持跨项目调用的核心机制,它保持了各子项目的独立性,又赋予了单体仓库灵活的 CLI 编排能力——无需全局安装、不污染环境,真正实现“按需加载、即用即走”。

















