astral-sh/uv

uv-pep440

crates/uv-pep440/ implements PEP 440: Python version identifiers, version specifiers, and version ranges. It is one of the foundational crates the rest of uv builds on.

Purpose

Parse, compare, and operate on Python versions and version specifiers (>=1.0,<2, ~=1.4.5, ==1.0.*, …) at the speed and correctness uv's resolver requires. The crate is used everywhere a version comes up: distributions, requirements, lockfiles, the resolver, the build frontend.

It is one of the oldest parts of uv — imported in October 2023 from the standalone pep440-rs crate (#32), then absorbed and renamed.

Directory layout

crates/uv-pep440/src/
├── lib.rs                  # Re-exports + MIN_VERSION / MAX_VERSION constants
├── version.rs              # 162k chars: Version, VersionParseError, parsing rules
├── version_specifier.rs    # 76k chars: VersionSpecifier, VersionSpecifiers, parsing
└── version_ranges.rs       # 26k chars: bridge to astral-version-ranges (sealed range arithmetic)

Key abstractions

Type	File	Role
`Version`	`version.rs`	A normalized PEP 440 version. Stores epoch, release segments, pre/post/dev/local.
`VersionSpecifier`	`version_specifier.rs`	A single specifier: operator (`==`, `!=`, `<=`, `>=`, `<`, `>`, `~=`, `===`) + version.
`VersionSpecifiers`	`version_specifier.rs`	An AND-conjunction of specifiers (e.g., `>=1.0,<2`).
`VersionRanges`	`version_ranges.rs`	Sealed range arithmetic over versions, used by the resolver to intersect/exclude.
`Prerelease`	`version.rs`	Pre-release segment (`a1`, `b2`, `rc3`).
`MIN_VERSION` / `MAX_VERSION`	`lib.rs`	Sentinel boundaries used by the resolver.
`release_specifiers_to_ranges`	re-exported	Helper for converting Python release specifiers into version-range objects.

How it works

Versions

A PEP 440 Version is segmented into:

Epoch (rare; integers separated from the rest by !).
Release (1.2.3 style, arbitrary depth).
Pre-release (a1, b1, rc1).
Post-release (.post1).
Dev release (.dev1).
Local version (+abc.def, after a +).

Parsing is hand-written and aggressively normalizing: 01.2-Rc.1 parses to 1.2rc1. The struct supports both lossless round-trip and a normalized form. Comparison follows PEP 440's ordering rules exactly, including the subtle behavior of pre- and post-releases.

Specifiers

VersionSpecifier is one of ==, !=, <=, >=, <, >, ~=, or === (arbitrary equality). VersionSpecifiers is a vector of specifiers, conjoined with AND. The crate provides:

contains(&Version) -> bool for direct membership tests.
to_ranges for converting into the resolver's range arithmetic.
Display implementations that produce canonical strings.

The ~= operator is implemented carefully: ~=1.4.5 means "compatible with 1.4.5", which PEP 440 defines as >=1.4.5,<1.5.

Range arithmetic

version_ranges.rs bridges to the astral-version-ranges crate (a fork of version-ranges). The resolver operates on ranges (intersections, complements) rather than individual specifiers, which is how PubGrub explores constraints.

Performance details

rkyv archives. With the rkyv feature, Version and VersionSpecifiers can be stored as zero-copy archived bytes — important for large lockfiles and registry caches.
tracing feature. Optional, off in release builds.
version-ranges feature. Pulled in by default for the resolver.

The crate is heavily tested with a property-based test suite (crates/uv-pep440/src/version.rs has many #[test] functions covering edge cases like leading zeros, mixed case in pre/post/dev markers, and the local-version segment).

Integration points

uv-pep508 uses Version and VersionSpecifiers in its Requirement type.
uv-resolver is the heaviest user — every constraint and candidate carries a Version, and VersionRanges is the language the solver speaks.
uv-distribution-types uses Version in distribution identity.
uv-python uses Version in PythonVersion and PythonRequirement.

Entry points for modification

A new operator or syntax — version_specifier.rs parser and the comparison logic.
Performance work — version.rs is hot, especially parsing. Most optimization happens there.

Key source files

File	Purpose
`crates/uv-pep440/src/version.rs`	The 162k-character `Version` implementation.
`crates/uv-pep440/src/version_specifier.rs`	Specifiers, parsing, and ordering.
`crates/uv-pep440/src/version_ranges.rs`	Range arithmetic bridge.