From 7520fe6c25d2ab369e6d9295c8ca4909ce4bc896 Mon Sep 17 00:00:00 2001
From: luyiming <luyimingchn@gmail.com>
Date: Sat, 7 Mar 2026 00:50:11 +0800
Subject: [PATCH] Improve documentation on virtual dependencies (#18346)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

<!--
Thank you for contributing to uv! To help us out with reviewing, please
consider the following:

- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title?
- Does this pull request include references to any relevant issues?
-->

## Summary

<!-- What's the purpose of the change? What does it do, and why? -->

The current documentation for virtual dependencies is somewhat confusing
because it places the sentence

> "the package will be built even if a build system is not declared"

immediately after introducing `tool.uv.package = false`. This makes it
sound as if the package might still be built when `package = false` is
set.

In reality, that sentence describes the *default behavior of path
dependencies* (when `package = false` is not set). The revised wording
clarifies that:

- `package = false` → the dependency becomes virtual (its dependencies
are installed, but the package itself is not built or installed)
- otherwise → uv treats the path dependency as a normal package and will
attempt to build it, even without a `[build-system]`.
---
 docs/concepts/projects/dependencies.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/concepts/projects/dependencies.md b/docs/concepts/projects/dependencies.md
index 93094e451..8ddd396ba 100644
--- a/docs/concepts/projects/dependencies.md
+++ b/docs/concepts/projects/dependencies.md
@@ -859,9 +859,9 @@ uv allows dependencies to be "virtual", in which the dependency itself is not in
 By default, dependencies are never virtual.
 
 A dependency with a [`path` source](#path) can be virtual if it explicitly sets
-[`tool.uv.package = false`](../../reference/settings.md#package). Unlike working _in_ the dependent
-project with uv, the package will be built even if a [build system](./config.md#build-systems) is
-not declared.
+[`tool.uv.package = false`](../../reference/settings.md#package). Without this setting, uv treats
+the path dependency as a normal package and will attempt to build it, even if the project does not
+declare a [build system](./config.md#build-systems).
 
 To treat a dependency as virtual, set `package = false` on the source:
 
@@ -885,8 +885,9 @@ bar = { path = "../projects/bar", package = true }
 ```
 
 Similarly, a dependency with a [`workspace` source](#workspace-member) can be virtual if it
-explicitly sets [`tool.uv.package = false`](../../reference/settings.md#package). The workspace
-member will be built even if a [build system](./config.md#build-systems) is not declared.
+explicitly sets [`tool.uv.package = false`](../../reference/settings.md#package). Without this
+setting, the workspace member will be built even if a [build system](./config.md#build-systems) is
+not declared.
 
 Workspace members that are _not_ dependencies can be virtual by default, e.g., if the parent
 `pyproject.toml` is: