uv/docs/preview/workspaces.md

Warning: This documentation refers to experimental features that may change.

Workspaces

Workspaces help organize large codebases by splitting them into multiple packages with independent dependencies.

When using the uv pip interface, workspace dependencies behave like automatic editable path dependencies. Using the uv project interface, all of the workspace packages are locked together. uv run installs only the current package (unless overridden with --package) and its workspace and non-workspace dependencies.

Configuration

A workspace can be created by adding a tool.uv.workspace to a pyproject.toml that is the workspace root. This table contains members (mandatory) and exclude (optional), with lists of globs of directories:

[tool.uv.workspace]
members = ["packages/*", "examples/*"]
exclude = ["example/excluded_example"]

If tool.uv.sources is defined in the workspace root, it applies to all packages, unless overridden in the tool.uv.sources of a specific project.

Common usage

There a two main usage patterns: A root package and helpers, and the flat workspace. The root workspace layout defines one main package in the root of the repository, with helper packages in packages. In the flat layout, all packages are in the packages directory, and the root pyproject.toml defines a so-called virtual workspace.

Root package and helpers: In this layout albatross/pyproject.toml has both a project section and a tool.uv.workspace section.

albatross
├── packages
│   ├── provider_a
│   │   ├── pyproject.toml
│   │   └── src
│   │       └── provider_a
│   │           ├── __init__.py
│   │           └── foo.py
│   └── provider_b
│       ├── pyproject.toml
│       └── src
│           └── provider_b
│               ├── __init__.py
│               └── bar.py
├── pyproject.toml
├── README.md
├── uv.lock
└── src
    └── albatross
        └── main.py

Flat workspace: In this layout albatross/pyproject.toml has only a tool.uv.workspace section, but no project.

albatross
├── packages
│   ├── albatross
│   │   ├── pyproject.toml
│   │   └── src
│   │       └── albatross
│   │           ├── __init__.py
│   │           └── foo.py
│   ├── provider_a
│   │   ├── pyproject.toml
│   │   └── src
│   │       └── provider_a
│   │           ├── __init__.py
│   │           └── foo.py
│   └── provider_b
│       ├── pyproject.toml
│       └── src
│           └── provider_b
│               ├── __init__.py
│               └── bar.py
├── pyproject.toml
├── README.md
└── uv.lock