Mathieu Kniewallner
c9637f00f0
## Summary A bunch of fixes and improvements on different parts of the documentation. For Docker documentation changes, links to the relevant documentations have been included in the commit messages.
89 lines
2.8 KiB
Markdown
89 lines
2.8 KiB
Markdown
**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:
|
|
|
|
```toml
|
|
[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
|
|
```
|