mirror of
https://github.com/astral-sh/uv.git
synced 2025-08-04 19:08:04 +00:00
1ee201da5a
A ton of work remaining here, pushing so I can preview things rendered. Here's the [latest rendered documentation](https://astral-sh.github.io/uv/).
88 lines
2.8 KiB
Markdown
88 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
|
|
```
|