Skip to content

Commit fa6dd7e

Browse files
zaniebjtfmumm
authored andcommitted
Update documentation for path dependency packaging
1 parent 615b2e7 commit fa6dd7e

File tree

2 files changed

+44
-28
lines changed

2 files changed

+44
-28
lines changed

docs/concepts/projects/config.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -116,9 +116,9 @@ with the default build system.
116116
the presence of a `[build-system]` table is not required in other packages. For legacy reasons,
117117
if a build system is not defined, then `setuptools.build_meta:__legacy__` is used to build the
118118
package. Packages you depend on may not explicitly declare their build system but are still
119-
installable (e.g., the default behavior for [installing path sources](./dependencies.md#installing-path-sources)).
120-
Similarly, if you add a dependency on a local package or install it with `uv pip`, uv will
121-
always attempt to build and install it.
119+
installable. Similarly, if you [add a dependency on a local project](./dependencies.md#path)
120+
or install it with `uv pip`, uv will attempt to build and install it regardless of the presence
121+
of a `[build-system]` table.
122122

123123
### Build system options
124124

docs/concepts/projects/dependencies.md

Lines changed: 41 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -408,31 +408,11 @@ Or, a path to a project directory:
408408
$ uv add ~/projects/bar/
409409
```
410410

411-
### Path dependency installation
412-
413-
By default, a path dependency project is installed in the environment as a package, unless it is
414-
explicitly marked as a [non-package](./config.md#build-systems). This is true even if it lacks a
415-
[`[build-system]` table](./config.md#build-systems). If you'd like to override this behavior and
416-
ensure the path dependency is not installed as a package, set `package = false` on the source:
417-
418-
```toml title="pyproject.toml"
419-
[project]
420-
dependencies = ["bar"]
421-
422-
[tool.uv.sources]
423-
bar = { path = "../projects/bar", package = false }
424-
```
425-
426-
If the path dependency project is marked as a non-package, but you'd like to install it as a
427-
package, set `package = true` on the source:
428-
429-
```toml title="pyproject.toml"
430-
[project]
431-
dependencies = ["bar"]
411+
!!! important
432412

433-
[tool.uv.sources]
434-
bar = { path = "../projects/bar", package = true }
435-
```
413+
When using a directory as a path dependency, uv will attempt to build and install the target as
414+
a package by default. See the [virtual dependency](#virtual-dependencies) documentation for
415+
details.
436416

437417
An [editable installation](#editable-dependencies) is not used for path dependencies by default. An
438418
editable installation may be requested for project directories:
@@ -451,7 +431,10 @@ dependencies = ["bar"]
451431
bar = { path = "../projects/bar", editable = true }
452432
```
453433

454-
For multiple packages in the same repository, [_workspaces_](./workspaces.md) may be a better fit.
434+
!!! tip
435+
436+
For multiple packages in the same repository, [_workspaces_](./workspaces.md) may be a better
437+
fit.
455438

456439
### Workspace member
457440

@@ -820,6 +803,39 @@ Or, to opt-out of using an editable dependency in a workspace:
820803
$ uv add --no-editable ./path/foo
821804
```
822805

806+
## Virtual dependencies
807+
808+
uv allows dependencies to be "virtual", in which the dependency itself is not installed as a
809+
[package](./config.md#project-packaging), but its dependencies are.
810+
811+
By default, only workspace members without build systems declared are virtual.
812+
813+
A dependency with a [`path` source](#path) is not virtual unless it explicitly sets
814+
[`tool.uv.package = false`](../../reference/settings.md#package). Unlike working _in_ the dependent
815+
project with uv, the package will be built even if a [build system](./config.md#build-systems) is
816+
not declared.
817+
818+
To treat a dependency as virtual, set `package = false` on the source:
819+
820+
```toml title="pyproject.toml"
821+
[project]
822+
dependencies = ["bar"]
823+
824+
[tool.uv.sources]
825+
bar = { path = "../projects/bar", package = false }
826+
```
827+
828+
Similarly, if a dependency sets `tool.uv.package = false`, it can be overridden by declaring
829+
`package = true` on the source:
830+
831+
```toml title="pyproject.toml"
832+
[project]
833+
dependencies = ["bar"]
834+
835+
[tool.uv.sources]
836+
bar = { path = "../projects/bar", package = true }
837+
```
838+
823839
## Dependency specifiers (PEP 508)
824840

825841
uv uses

0 commit comments

Comments
 (0)