diff --git a/docs/pip/compatibility.md b/docs/pip/compatibility.md index 96d1e38ba37b9..c5177a7e178a7 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,23 @@ 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. 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 + + 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 -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