⚠️

重要前提

安装AI Skills的关键前提是：必须科学上网，且开启TUN模式，这一点至关重要，直接决定安装能否顺利完成，在此郑重提醒三遍：科学上网，科学上网，科学上网。查看完整安装教程 →

UV Workspaces 使用指南：Python Monorepo 与多包项目管理快速参考

uv-workspaces by laurigates/claude-plugins

65 周安装量

23 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/laurigates/claude-plugins --skill uv-workspaces

Python Web框架项目管理工程/构建系统

🇨🇳中文介绍

UV 工作区

使用 UV 工作区管理 monorepo 和多包项目的快速参考。

何时使用此技能

在以下情况使用此技能...	在以下情况请改用其他技能...
设置具有共享依赖项的 Python monorepo	管理单个包 (`uv-project-management`)
配置工作区成员和包间依赖	添加 git/URL 依赖项 (`uv-advanced-dependencies`)
使用 `--package` 或 `--all-packages` 标志	构建/发布到 PyPI (`python-packaging`)
创建虚拟工作区（根目录无项目）	管理 Python 版本 (`uv-python-versions`)

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

根目录 pyproject.toml

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

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

# 可选：排除特定成员
exclude = ["packages/experimental"]

虚拟工作区（无根包）

当根目录纯粹是组织性的且本身不是包时，省略 [project] 表：

# 根目录 pyproject.toml — 虚拟工作区（无 [project] 表）
[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",       # 工作区成员
    "fastapi",       # 外部依赖（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 适用于 所有成员，除非被覆盖。

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

# 根目录 pyproject.toml — 适用于所有成员
[tool.uv.sources]
my-utils = { workspace = true }

# packages/legacy/pyproject.toml — 需要固定版本
[tool.uv.sources]
my-utils = { path = "../utils-v1" }  # 完全覆盖根目录源

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

requires-python 解析

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

# packages/core: requires-python = ">=3.10"
# packages/api:  requires-python = ">=3.11"
# 实际生效:     requires-python = ">=3.11"

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

工作区成员依赖项 始终是可编辑的 — 源代码更改立即可用，无需重新安装。

命令	默认作用域	覆盖选项
`uv lock`	整个工作区	—
`uv sync`	仅工作区根目录	`--package`, `--all-packages`
`uv run`	仅工作区根目录	`--package`, `--all-packages`
`uv build`	所有成员	`--package`

工作区依赖 vs 路径依赖

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

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

# 首先安装依赖项（缓存层）
COPY pyproject.toml uv.lock packages/*/pyproject.toml ./
RUN uv sync --frozen --no-install-workspace

# 然后安装项目（频繁更改）
COPY . .
RUN uv sync --frozen

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

场景	命令
同步所有成员	`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。

🇺🇸English

UV Workspaces

Quick reference for managing monorepo and multi-package projects with UV workspaces.

When to Use This Skill

Use this skill when...	Use another skill instead when...
Setting up a Python monorepo with shared deps	Managing a single package (`uv-project-management`)
Configuring workspace members and inter-package deps	Adding git/URL dependencies (`uv-advanced-dependencies`)
Using `--package` or `--all-packages` flags	Building/publishing to PyPI (`python-packaging`)
Creating virtual workspaces (root with no project)	Managing Python versions (`uv-python-versions`)
Debugging workspace dependency resolution	Running standalone scripts (`uv-run`)

Quick Reference

Workspace Structure

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

Root 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"]

Virtual Workspace (No Root Package)

When the root is purely organizational and not a package itself, omit the [project] table:

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

The root is not a workspace member
All members live in subdirectories
uv run and uv sync require --package or --all-packages (will error without them)

Member 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 }

Common Commands

Operation	Command
Sync workspace root	`uv sync`
Sync all members	`uv sync --all-packages`
Sync specific member	`uv sync --package my-api`
Run in member context	`uv run --package my-api python script.py`
Lock entire workspace	`uv lock`
Upgrade a dependency	`uv lock --upgrade-package requests`

Key Behaviors

Source Inheritance

Root tool.uv.sources apply to all members unless overridden.

Use case : Define workspace sources in root for all members, override only when a specific member needs a different version:

# 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

Override is per-dependency and total — if a member defines a source for a dependency, the root source for that dependency is ignored completely.

requires-python Resolution

The workspace enforces the intersection of all members' requires-python:

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

All members must have compatible Python version requirements.

Editable Installations

Workspace member dependencies are always editable — source changes are immediately available without reinstallation.

Default Scope

Command	Default scope	Override
`uv lock`	Entire workspace	—
`uv sync`	Workspace root only	`--package`, `--all-packages`
`uv run`	Workspace root only	`--package`, `--all-packages`

Workspace vs Path Dependencies

Feature	`{ workspace = true }`	`{ path = "../pkg" }`
Shared lockfile	Yes	No
Always editable	Yes	Optional
Must be workspace member	Yes	No
`--package` flag works	Yes	No
Conflicting deps allowed	No	Yes

Use path dependencies when members need conflicting requirements or separate virtual environments.

Docker Layer Caching

# 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

Flag	Effect
`--no-install-project`	Skip current project, install deps only
`--no-install-workspace`	Skip all workspace members, install deps only
`--no-install-package <name>`	Skip specific package(s)
`--frozen`	Skip lockfile freshness check

Agentic Optimizations

Context	Command
Sync all members	`uv sync --all-packages`
CI sync (frozen)	`uv sync --all-packages --frozen`
Test specific member	`uv run --package my-core pytest --dots --bail=1`
Test all members	`uv run --all-packages pytest --dots --bail=1`
Lock with upgrade	`uv lock --upgrade-package <dep>`
Build one package	`uv build --package my-core`

UV Workspaces 使用指南：Python Monorepo 与多包项目管理快速参考

🇨🇳中文介绍

UV 工作区

何时使用此技能

相关 Skills

快速参考

工作区结构