Workspaces

uv supports Cargo-style workspaces: a top-level pyproject.toml declares [tool.uv.workspace] with a list of members globs, and every member is a separate package with its own pyproject.toml.

Discovery

Workspace::discover (uv-workspace) walks up from the current directory:

1. Find a pyproject.toml.
2. If it has [tool.uv.workspace], this is the root.
3. If it doesn't, walk up until you find a parent that does — and that parent's members glob includes us.
4. Otherwise, the current pyproject.toml is a standalone project.

The discovery rules also handle:

• Exclusions — exclude = ["legacy/*"].
• Source overrides — [tool.uv.sources] with workspace = true.
• Mixed monorepos — workspaces nested in larger non-uv repos.

Locking

A workspace shares a single uv.lock at the root. Resolution must satisfy all members simultaneously, with conflicts surfaced via [tool.uv.conflicts].

This is one of the harder parts of universal resolution — the resolver has to fork by member-environment combinations and produce an output that's installable for any subset.

uv sync in a workspace

uv sync defaults to "the package containing my CWD." --all-packages syncs everything; --package <name> targets one. The lockfile is shared so the resolution doesn't change.

See also

• crates/uv-workspace, features/dependency-resolution.