Document the effect of ordering on package priority (#6211)

Closes https://github.com/astral-sh/uv/issues/6209
Closes https://github.com/astral-sh/uv/issues/5474

PIP_COMPATIBILITY.md

@@ -447,3 +447,11 @@ is omitted.
 While this is not strictly compliant with [PEP 440](https://peps.python.org/pep-0440/), it _is_
 consistent with
 [pip](https://github.com/pypa/pip/blob/24.1.1/src/pip/_internal/resolution/resolvelib/candidates.py#L540).
+
+## Package priority
+
+There are usually many possible solutions given a set of requirements — a resolver must choose
+between the solutions. Unlike pip, uv's resolver uses the ordering provided of packages to determine
+the default priority. This means that uv's resolution can differ based on the order of the packages.
+For example, `uv pip install foo bar` would prioritize a newer version of `foo` over `bar`.
+Similarly, this applies to the ordering of requirements in input files to `uv pip compile`.

crates/uv-cli/src/lib.rs

@@ -692,10 +692,13 @@ fn parse_maybe_file_path(input: &str) -> Result<Maybe<PathBuf>, String> {
 pub struct PipCompileArgs {
     /// Include all packages listed in the given `requirements.in` files.
     ///
-    /// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, uv will
+    /// If a `pyproject.toml`, `setup.py`, or `setup.cfg` file is provided, uv will extract the
-    /// extract the requirements for the relevant project.
+    /// requirements for the relevant project.
     ///
     /// If `-` is provided, then requirements will be read from stdin.
+    ///
+    /// The order of the requirements files and the requirements in them is used to determine
+    /// priority during resolution.
     #[arg(required(true), value_parser = parse_file_path)]
     pub src_file: Vec<PathBuf>,
 
@@ -1245,6 +1248,8 @@ pub struct PipSyncArgs {
 #[allow(clippy::struct_excessive_bools)]
 pub struct PipInstallArgs {
     /// Install all listed packages.
+    ///
+    /// The order of the packages is used to determine priority during resolution.
     #[arg(group = "sources")]
     pub package: Vec<String>,
 

docs/pip/compatibility.md

@@ -395,3 +395,11 @@ will include all index URLs when `--emit-index-url` is passed, including the def
 By default, uv does not write any `--no-build` or `--only-binary` options to the output file, unlike
 `pip-compile`. To include these options in the output file, pass the `--emit-build-options` flag to
 `uv pip compile`.
+
+## Package priority
+
+There are usually many possible solutions given a set of requirements — a resolver must choose
+between the solutions. Unlike pip, uv's resolver uses the ordering provided of packages to determine
+the default priority. This means that uv's resolution can differ based on the order of the packages.
+For example, `uv pip install foo bar` would prioritize a newer version of `foo` over `bar`.
+Similarly, this applies to the ordering of requirements in input files to `uv pip compile`.

docs/reference/cli.md

@@ -3546,6 +3546,8 @@ uv pip compile [OPTIONS] <SRC_FILE>...
 
 <p>If <code>-</code> is provided, then requirements will be read from stdin.</p>
 
+<p>The order of the requirements files and the requirements in them is used to determine priority during resolution.</p>
+
 </dd></dl>
 
 <h3 class="cli-reference">Options</h3>
@@ -4191,7 +4193,9 @@ uv pip install [OPTIONS] <PACKAGE|--requirement <REQUIREMENT>|--editable <EDITAB
 
 <h3 class="cli-reference">Arguments</h3>
 
-<dl class="cli-reference"><dt><code>PACKAGE</code></dt><dd><p>Install all listed packages</p>
+<dl class="cli-reference"><dt><code>PACKAGE</code></dt><dd><p>Install all listed packages.</p>
+
+<p>The order of the packages is used to determine priority during resolution.</p>
 
 </dd></dl>