Skip to content

Update pip pre-release compatibility information #17788

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zanieb merged 5 commits into from
Jan 31, 2026
+11 −14
Merged

Update pip pre-release compatibility information #17788

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1403e3e
Update pip pre-release compatibility information
notatallshaw Jan 31, 2026
7a65a81
Update docs/pip/compatibility.md
notatallshaw Jan 31, 2026
787dcda
Further clarification
notatallshaw Jan 31, 2026
33cfbd5
Add note
notatallshaw Jan 31, 2026
4c3e493
Notify the note
notatallshaw Jan 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 11 additions & 14 deletions docs/pip/compatibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Copy Markdown
Member

@zanieb zanieb Jan 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was previously relying on the renderer to change this to the next number


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.
Expand All @@ -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

Expand Down
Loading