uv-workspaces

UV 工作区

使用 UV 工作区管理单体仓库和多包项目的快速参考。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用其他技能……
设置共享依赖的 Python 单体仓库	管理单个包（uv-project-management）
配置工作区成员和包间依赖	添加 git/URL 依赖（uv-advanced-dependencies）
使用 --package 或 --all-packages 标志	构建/发布到 PyPI（python-packaging）
创建虚拟工作区（根目录没有项目）	管理 Python 版本（uv-python-versions）
调试工作区依赖解析	运行独立脚本（uv-run）

快速参考

工作区结构

my-workspace/
├── pyproject.toml          # Root workspace config
├── uv.lock                 # Shared lockfile (all members)
├── packages/
│   ├── core/
│   │   ├── pyproject.toml
│   │   └── src/core/
│   ├── api/
│   │   ├── pyproject.toml
│   │   └── src/api/
│   └── cli/
│       ├── pyproject.toml
│       └── src/cli/
└── README.md

根目录 pyproject.toml

[project]
name = "my-workspace"
version = "0.1.0"
requires-python = ">=3.11"

[tool.uv.workspace]
members = ["packages/*"]

# Optional: exclude specific members
exclude = ["packages/experimental"]

虚拟工作区（无根包）

当根目录仅用于组织，且自身不是一个包时，省略 [project] 表：

# Root pyproject.toml — virtual workspace (no [project] table)
[tool.uv.workspace]
members = ["packages/*"]

• 根目录不是工作区成员
• 所有成员都位于子目录中
• uv run 和 uv sync 需要 --package 或 --all-packages（否则会报错）

成员 pyproject.toml

[project]
name = "my-api"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "my-core",       # Workspace member
    "fastapi",       # External (PyPI)
]

[tool.uv.sources]
my-core = { workspace = true }

常用命令

操作	命令
同步工作区根目录	uv sync
同步所有成员	uv sync --all-packages
同步指定成员	uv sync --package my-api
在成员上下文中运行	uv run --package my-api python script.py
锁定整个工作区	uv lock
升级依赖	uv lock --upgrade-package requests
构建指定包	uv build --package my-core
向成员添加依赖	cd packages/api && uv add requests
添加工作区依赖	cd packages/api && uv add ../core

关键行为

来源继承

根目录的 tool.uv.sources 会应用于所有成员，除非成员另行覆盖。

使用场景：在根目录定义所有成员的工作区来源，仅在某个成员需要不同版本时覆盖：

# Root pyproject.toml — applies to all members
[tool.uv.sources]
my-utils = { workspace = true }

# packages/legacy/pyproject.toml — needs pinned version
[tool.uv.sources]
my-utils = { path = "../utils-v1" }  # Overrides root entirely

覆盖是按依赖进行且完全替代的——如果成员为某项依赖定义了来源，该依赖的根目录来源将被完全忽略。

requires-python 解析

工作区强制要求所有成员的 requires-python 交集：

# packages/core: requires-python = ">=3.10"
# packages/api:  requires-python = ">=3.11"
# Effective:     requires-python = ">=3.11"

所有成员的 Python 版本要求必须兼容。

可编辑安装

工作区成员依赖始终以可编辑方式安装——源代码变更会立即生效，无需重新安装。

默认范围

命令	默认范围	覆盖方式
uv lock	整个工作区	—
uv sync	仅工作区根目录	--package、--all-packages
uv run	仅工作区根目录	--package、--all-packages
uv build	所有成员	--package

工作区依赖与路径依赖

特性	{ workspace = true }	{ path = "../pkg" }
共享锁定文件	是	否
始终可编辑	是	可选
必须是工作区成员	是	否
--package 标志可用	是	否
允许依赖冲突	否	是

当成员需要互相冲突的依赖要求或独立的虚拟环境时，请使用路径依赖。

Docker 层缓存

# Install deps first (cached layer)
COPY pyproject.toml uv.lock packages/*/pyproject.toml ./
RUN uv sync --frozen --no-install-workspace

# Then install project (changes frequently)
COPY . .
RUN uv sync --frozen

标志	效果
--no-install-project	跳过当前项目，仅安装依赖
--no-install-workspace	跳过所有工作区成员，仅安装依赖
--no-install-package <name>	跳过指定的包
--frozen	跳过锁定文件新鲜度检查

Agentic 优化

上下文	命令
同步所有成员	uv sync --all-packages
CI 同步（冻结）	uv sync --all-packages --frozen
测试指定成员	uv run --package my-core pytest --dots --bail=1
测试所有成员	uv run --all-packages pytest --dots --bail=1
升级并锁定	uv lock --upgrade-package <dep>
构建单个包	uv build --package my-core
Docker 依赖层	uv sync --frozen --no-install-workspace

另请参阅

• uv-project-management — 管理单个包
• uv-advanced-dependencies — 路径和 Git 依赖
• python-packaging — 构建和发布工作区包

有关详细的工作区模式（虚拟工作区、Docker 集成、源继承、同步策略）、CI/CD 示例和故障排除，请参阅 REFERENCE.md。