From b031e9fe8313ef0a6af15c93d689473e8ae63d69 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 8 Jan 2026 21:04:41 +0000 Subject: [PATCH] Clarify that `uv run` uses inexact syncing by default The documentation previously said "syncing is exact by default" without clarifying that this applies only to `uv sync`, not `uv run`. This led users to incorrectly believe that `uv run` would remove extraneous packages from their environment. This commit updates the documentation to: - Rename the section to "Handling of extraneous packages" - Explicitly state that `uv sync` uses exact syncing while `uv run` uses inexact syncing by default - Document the `--exact` flag for `uv run` - Add a note in the projects guide clarifying that extraneous packages may be present Fixes #14230 --- docs/concepts/projects/sync.md | 16 ++++++++++++---- docs/guides/projects.md | 10 ++++++++-- docs/js/extra.js | 2 ++ 3 files changed, 22 insertions(+), 6 deletions(-) diff --git a/docs/concepts/projects/sync.md b/docs/concepts/projects/sync.md index f3a7fb80b22c9..9d48df6a600df 100644 --- a/docs/concepts/projects/sync.md +++ b/docs/concepts/projects/sync.md @@ -89,17 +89,25 @@ To opt-out of this behavior, use the `--no-editable` option. If the project does not define a build system, it will not be installed. See the [build systems](./config.md#build-systems) documentation for details. -### Retaining extraneous packages +### Handling of extraneous packages -Syncing is "exact" by default, which means it will remove any packages that are not present in the -lockfile. +`uv sync` performs "exact" syncing by default, which means it will remove any packages that are not +present in the lockfile. -To retain extraneous packages, use the `--inexact` option: +To retain extraneous packages, use the `--inexact` flag: ```console $ uv sync --inexact ``` +In contrast, `uv run` uses "inexact" syncing by default, ensuring that all required packages are +installed but not removing extraneous packages. To enable exact syncing with `uv run`, use the +`--exact` flag: + +```console +$ uv run --exact ... +``` + ### Syncing optional dependencies uv reads optional dependencies from the `[project.optional-dependencies]` table. These are diff --git a/docs/guides/projects.md b/docs/guides/projects.md index 56cd672bf8d51..5bb8ede994ae4 100644 --- a/docs/guides/projects.md +++ b/docs/guides/projects.md @@ -198,8 +198,14 @@ version. Prior to every `uv run` invocation, uv will verify that the lockfile is up-to-date with the `pyproject.toml`, and that the environment is up-to-date with the lockfile, keeping your project -in-sync without the need for manual intervention. `uv run` guarantees that your command is run in a -consistent, locked environment. +in-sync without the need for manual intervention. `uv run` guarantees that your command is run in an +environment with all required dependencies at their locked versions. + +!!! note + + `uv run` does not remove extraneous packages (those not in the lockfile) from the environment + by default. See [handling of extraneous packages](../concepts/projects/sync.md#handling-of-extraneous-packages) + for details. For example, to use `flask`: diff --git a/docs/js/extra.js b/docs/js/extra.js index 1c5fdf03f43f1..6ff37bc17269b 100644 --- a/docs/js/extra.js +++ b/docs/js/extra.js @@ -88,6 +88,8 @@ document$.subscribe(function () { "concepts/projects/run/#legacy-scripts-on-windows", "concepts/projects/sync/#checking-if-the-lockfile-is-up-to-date": "concepts/projects/sync/#checking-the-lockfile", + "concepts/projects/sync/#retaining-extraneous-packages": + "concepts/projects/sync/#handling-of-extraneous-packages", "concepts/authentication/#git-authentication": "concepts/authentication/git/", "concepts/authentication/#git-credential-helpers":