
在 uv 驱动的 Python 单体仓库中,可通过 uv run --project 显式指定项目根目录,使任意位置都能调用该子项目 pyproject.toml 中定义的 [project.scripts],无需切换工作目录或安装包。
在 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)设计理念。
当现有的脚本或服务需要将作用域化的仓库工作委托给 Claude Code 并以编程方式消费结构化响应时,请使用 Claude Agent SDK for Python。
⚠️ 注意事项:
-
--project路径必须指向包含有效pyproject.toml的目录(即子项目根目录),而非.toml文件本身; - 若脚本依赖尚未解析的依赖,uv 会自动按需构建隔离环境(首次运行稍慢,后续缓存加速);
- 不支持通配符或工作区级批量注册脚本;每个调用仍需显式指定
--project; - 避免与
--python混用导致环境冲突,建议优先通过子项目requires-python和dependencies管理兼容性。
总结:uv run --project 是 monorepo 场景下跨目录调用脚本的标准、轻量且可靠的方式,兼顾隔离性与便捷性,是替代传统 pip install -e . 或全局 PATH 注入的最佳实践。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!










