From 1403e3e4db3ebfc1e75e25b8bb5b448171339329 Mon Sep 17 00:00:00 2001 From: Damian Shaw Date: Sat, 31 Jan 2026 15:48:08 -0500 Subject: [PATCH 1/5] Update pip pre-release compatibility information --- docs/pip/compatibility.md | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/docs/pip/compatibility.md b/docs/pip/compatibility.md index 96d1e38ba37b9..8f2e1dab0ee68 100644 --- a/docs/pip/compatibility.md +++ b/docs/pip/compatibility.md @@ -44,7 +44,7 @@ By default, uv will accept pre-release versions during dependency resolution in 1. If the package is a direct dependency, and its version markers include a pre-release specifier (e.g., `flask>=2.0.0rc1`). -1. If _all_ published versions of a package are pre-releases. +2. If _all_ published versions of a package are pre-releases. If dependency resolution fails due to a transitive pre-release, uv will prompt the user to re-run with `--prerelease allow`, to allow pre-releases for all dependencies. @@ -53,26 +53,19 @@ Alternatively, you can add the transitive dependency to your `requirements.in` f specifier (e.g., `flask>=2.0.0rc1`) to opt in to pre-release support for that specific dependency. In sum, uv needs to know upfront whether the resolver should accept pre-releases for a given -package. `pip`, meanwhile, _may_ respect pre-release identifiers in transitive dependencies -depending on the order in which the resolver encounters the relevant specifiers -([#1641](https://github.com/astral-sh/uv/issues/1641#issuecomment-1981402429)). +package. `pip`, meanwhile, respects pre-release identifiers in transitive dependencies, as well as +allows pre-releases of transitive dependencies if no stable versions are available. Pre-releases are [notoriously difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) to -model, and are a frequent source of bugs in packaging tools. Even `pip`, which is viewed as a -reference implementation, has a number of open questions around pre-release handling -([#12469](https://github.com/pypa/pip/issues/12469), -[#12470](https://github.com/pypa/pip/issues/12470), -[#40505](https://discuss.python.org/t/handling-of-pre-releases-when-backtracking/40505/20), etc.). -uv's pre-release handling is _intentionally_ limited and _intentionally_ requires user opt-in for -pre-releases, to ensure correctness. +model, and are a frequent source of bugs in packaging tools. uv's pre-release handling is +_intentionally_ limited and _intentionally_ requires user opt-in for pre-releases, to ensure +correctness. In the future, uv _may_ support pre-release identifiers in transitive dependencies. However, it's likely contingent on evolution in the Python packaging specifications. The existing PEPs [do not cover "dependency resolution"](https://discuss.python.org/t/handling-of-pre-releases-when-backtracking/40505/17) -and are instead focused on behavior for a _single_ version specifier. As such, there are unresolved -questions around the correct and intended behavior for pre-releases in the packaging ecosystem more -broadly. +and are instead focused on behavior for a _single_ version specifier. ## Packages that exist on multiple indexes From 7a65a8127ac98941015439a589ec460ccfa00b53 Mon Sep 17 00:00:00 2001 From: Damian Shaw Date: Sat, 31 Jan 2026 15:55:54 -0500 Subject: [PATCH 2/5] Update docs/pip/compatibility.md Co-authored-by: Charlie Marsh --- docs/pip/compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pip/compatibility.md b/docs/pip/compatibility.md index 8f2e1dab0ee68..dc29696e42059 100644 --- a/docs/pip/compatibility.md +++ b/docs/pip/compatibility.md @@ -53,7 +53,7 @@ Alternatively, you can add the transitive dependency to your `requirements.in` f specifier (e.g., `flask>=2.0.0rc1`) to opt in to pre-release support for that specific dependency. In sum, uv needs to know upfront whether the resolver should accept pre-releases for a given -package. `pip`, meanwhile, respects pre-release identifiers in transitive dependencies, as well as +package. `pip`, meanwhile, respects pre-release identifiers in transitive dependencies, and allows pre-releases of transitive dependencies if no stable versions are available. Pre-releases are From 787dcda99923f36e58b48160cb53a7c3f891c86d Mon Sep 17 00:00:00 2001 From: Damian Shaw Date: Sat, 31 Jan 2026 16:01:33 -0500 Subject: [PATCH 3/5] Further clarification --- docs/pip/compatibility.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pip/compatibility.md b/docs/pip/compatibility.md index dc29696e42059..efe2863268516 100644 --- a/docs/pip/compatibility.md +++ b/docs/pip/compatibility.md @@ -53,8 +53,8 @@ Alternatively, you can add the transitive dependency to your `requirements.in` f specifier (e.g., `flask>=2.0.0rc1`) to opt in to pre-release support for that specific dependency. In sum, uv needs to know upfront whether the resolver should accept pre-releases for a given -package. `pip`, meanwhile, respects pre-release identifiers in transitive dependencies, and -allows pre-releases of transitive dependencies if no stable versions are available. +package. `pip`, meanwhile, respects pre-release identifiers in transitive dependencies, and allows +pre-releases of transitive dependencies if no stable versions match the dependency requirements. Pre-releases are [notoriously difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) to From 33cfbd5037639cb2ea842bbdd6694139e8c215ef Mon Sep 17 00:00:00 2001 From: Damian Shaw Date: Sat, 31 Jan 2026 16:13:54 -0500 Subject: [PATCH 4/5] Add note --- docs/pip/compatibility.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/pip/compatibility.md b/docs/pip/compatibility.md index efe2863268516..19c6ce010faca 100644 --- a/docs/pip/compatibility.md +++ b/docs/pip/compatibility.md @@ -53,8 +53,9 @@ Alternatively, you can add the transitive dependency to your `requirements.in` f specifier (e.g., `flask>=2.0.0rc1`) to opt in to pre-release support for that specific dependency. In sum, uv needs to know upfront whether the resolver should accept pre-releases for a given -package. `pip`, meanwhile, respects pre-release identifiers in transitive dependencies, and allows +package. Meanwhile `pip`, respects pre-release identifiers in transitive dependencies, and allows pre-releases of transitive dependencies if no stable versions match the dependency requirements. +Note: this behavior was made consistent in `pip` 26.0. Pre-releases are [notoriously difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) to From 4c3e493fede9dc65792454db9c8ecdfb68698e35 Mon Sep 17 00:00:00 2001 From: Damian Shaw Date: Sat, 31 Jan 2026 16:21:11 -0500 Subject: [PATCH 5/5] Notify the note --- docs/pip/compatibility.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/pip/compatibility.md b/docs/pip/compatibility.md index 19c6ce010faca..c5177a7e178a7 100644 --- a/docs/pip/compatibility.md +++ b/docs/pip/compatibility.md @@ -55,7 +55,10 @@ specifier (e.g., `flask>=2.0.0rc1`) to opt in to pre-release support for that sp In sum, uv needs to know upfront whether the resolver should accept pre-releases for a given package. Meanwhile `pip`, respects pre-release identifiers in transitive dependencies, and allows pre-releases of transitive dependencies if no stable versions match the dependency requirements. -Note: this behavior was made consistent in `pip` 26.0. + +!!! note + + Prior to pip 26.0, this behavior was not consistent. Pre-releases are [notoriously difficult](https://pubgrub-rs-guide.netlify.app/limitations/prerelease_versions) to