Text of peps.python.org › pep-0766 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 766 – Explicit Priority Choices Among Multiple Indexes | peps.python.org

PEP 766 – Explicit Priority Choices Among Multiple Indexes PEP 766 – Explicit Priority Choices Among Multiple Indexes Author : Michael Sarahan <msarahan at gmail.com> Sponsor : Barry Warsaw <barry at python.org> Discussions-To : Discourse thread Status : Draft Type : Informational Topic : Packaging Created : 18-Nov-2024 Post-History : 18-Nov-2024 Table of Contents Abstract Motivation Specification “Version priority” “Index priority” Cache keys Ways that a request falls through to a lower priority index Mirroring Backwards Compatibility Security Implications How to Teach This Reference Implementation Rejected Ideas Open Issues Acknowledgements Copyright Abstract Package resolution is a key part of the Python user experience as the means of extending Python’s core functionality.

The experience of package resolution is mostly taken for granted until someone encounters a situation where the package installer does something they don’t expect. The installer behavior with multiple indexes has been a common source of unexpected behavior . Through its ubiquity, pip has long defined the standard expected behavior across other tools in the ecosystem, but Python installers are diverging with respect to how they handle multiple indexes.

At the core of this divergence is whether index contents are combined before resolving distributions, or each index is handled individually in order. pip merges all indexes before matching distributions, while uv matches distributions on one index before moving on to the next. Each approach has advantages and disadvantages. This PEP aims to describe each of these behaviors, which are referred to as “version priority” and “index priority” respectively, so that community discussions and troubleshooting can share a common vocabulary, and so that tools can implement predictable behavior based on these descriptions.

Motivation Python package users frequently find themselves in need of specifying an index or package source other than PyPI. There are many reasons for external indexes to exist: File size/quota limitations on PyPI Implementation variants, such as different GPU library builds in PyTorch Local builds of packages shared internally at an organization Situations where a local package has remote dependencies , and the user wishes to prioritize local packages over remote dependencies, while still falling back to remote dependencies where needed In most of these cases, it is not desirable to completely forego PyPI.

Instead, users generally want PyPI to still be a source of packages, but a lower priority source. Unfortunately, pip’s current design precludes this concept of priority . Some Python installer tools have developed alternative ways to handle multiple indexes that incorporate mechanisms to express index priority, such as uv and PDM . The innovation and the potential for customization is exciting, but it comes at the risk of further fragmenting the python packaging ecosystem, which is already perceived as one of Python’s weak points.

The motivation of this PEP is to encourage installers to provide more insight into how they handle multiple indexes, and to provide a vocabulary that can be common to the broader community. Specification “Version priority” This behavior is characterized by the installer always getting the “best” version of a package, regardless of the index that it comes from. “Best” is defined by the installer’s algorithm for optimizing the various traits of a package, also factoring in user input (such as preferring only binaries, or no binaries).

While installers may differ in their optimization criteria and user options, the general trait that all version priority installers share is that the index contents are collated prior to candidate selection. Version priority is most useful when all configured indexes are equally trusted and well-behaved regarding the distribution interchangeability assumption. Mirrors are especially well-behaved in this regard. That interchangeability assumption is what makes comparing distributions of a given package meaningful.

Without it, the installer is no longer comparing “apples to apples.” In practice, it is common for different indexes to have files that have different contents than other indexes, such as builds for special hardware, or differing metadata for the same package. Version priority behavior can lead to undesirable, unexpected outcomes in these cases, and this is where users generally look for some kind of index priority .

Additionally, when there is a difference in trust among indexes, version priority does not provide a way to prefer more trusted indexes over less trusted indexes. This has been exploited by dependency confusion attacks, and PEP 708 was proposed as a way of hard-coding a notion of trusted external indexes into the index. The “version priority” name is new, and introduction of new terms should always be minimized. This PEP looks toward the uv project, which refers to its implementation of the version priority behavior as “ unsafe-best-match .” Naming is really hard here.

On one hand, it isn’t accurate to call pip’s default behavior intrinsically “unsafe.” The addition of possibly malicious indexes is what introduces concern with this behavior. PEP 708 added a way to restrict installers from drawing packages from unexpected, potentially insecure indexes. On the other hand, the term “best-match” is technically correct, but also misleading. The “best match” varies by user and by application.

“Best” is technically correct in the sense that it is a global optimum according to the match criteria specified above, but that is not necessarily what is “best” in a user’s eyes. “Version priority” is a proposed term that avoids the concerns with the uv terminology, while approximating the behavior in the most user-identifiable way that packages are compared. “Index priority” In index priority, the resolver finds candidates for each index, one at a time.

The resolver proceeds to subsequent indexes only if the current package request has no viable candidates. Index priority does not combine indexes into one global, flat namespace. Because indexes are searched in order, the package from an earlier index will be preferred over a package from a later index, regardless of whether the later index had a better match with the installer’s optimization criteria. For a given installer, the optimization criteria and selection algorithm should be the same for both index priority and version priority.

It is only the treatment of multiple indexes that differs: all together for version priority, and individually for index priority. The order of specification of indexes determines their priority in the finding process. As a result, the way that installers load the index configuration must be predictable and reproducible. This PEP does not prescribe any particular mechanism, other than to say that installers should provide a way of ordering their collection of sources.

Installers should also ideally provide optional debugging output that provides insight into which index is being considered. Each package’s finder should start at the beginning of the list of indexes, so each package starts over with the index list. In other words, if one package has no valid candidates on the first index, but finds a hit on the second index, subsequent packages should still start their search on the first index, rather than starting on the second.

One desirable behavior that the index priority strategy implies is that there are no “surprise” updates, where a version bump on a lower-priority index wins out over a curated, approved higher-priority index. This is related to the security improvement of PEP 708 , where packages can restrict the external indexes that distributions can come from, but index priority is more configurable by end users. The package installs are only expected to change when ei

The rest of this page is on the live site.