semver

The semver crate is the reference Rust implementation for parsing and evaluating Semantic Versioning strings and version requirements, matching Cargo’s own interpretation of the SemVer spec. It exposes Version and VersionReq types that parse strings like 1.2.3-alpha.1+build5 and requirement expressions like >=1.2.3, <1.8.0, then evaluate whether a given version satisfies a requirement.

Written and maintained by David Tolnay, this is the same crate Cargo itself uses internally for dependency resolution, making it the de facto standard for any Rust tool that needs to work with version numbers or version constraints in a way that’s compatible with the crates.io ecosystem.

What You Get

• Version and VersionReq types with parse() methods for version strings and requirement expressions
• Full support for pre-release and build-metadata identifiers per the SemVer 2.0 spec
• Comparison and ordering implementations (Ord, PartialOrd) for Version following SemVer precedence rules
• Optional serde feature for serializing/deserializing versions and requirements
• no_std compatibility via the default-toggleable std feature

Common Use Cases

• Parsing and validating version numbers supplied by users, config files, or package manifests
• Implementing dependency resolution or compatibility checks that need to evaluate whether an installed version satisfies a stated requirement
• Building Cargo-adjacent tooling (linters, dependency auditors, build scripts) that needs to interpret Cargo.toml version requirements identically to Cargo itself
• Embedding version-aware feature gating or migration logic in libraries and CLIs

Under The Hood

Architecture The crate is organized into focused modules under src/: parse.rs handles the recursive-descent parsing of both Version and VersionReq grammars, eval.rs implements the requirement-matching logic (checking a Version against a VersionReq’s comparator list), identifier.rs provides a specialized small-string type for pre-release/build-metadata identifiers to avoid heap allocation in the common case, display.rs implements Display/Debug formatting, and impls.rs/serde.rs add trait implementations (Ord, Hash, optional serde::Serialize/Deserialize). lib.rs (569 lines) defines the core Version/VersionReq/Comparator/Prerelease/BuildMetadata types and re-exports the public API.

Tech Stack Pure Rust with edition 2021, zero required dependencies, and an optional serde_core dependency gated behind the serde feature; the crate supports no_std environments by default-toggling the std feature off. A build.rs script and criterion-based benchmarks (benches/parse.rs) track parsing performance, and a fuzz/ directory holds cargo-fuzz targets for the parser, reflecting the correctness-critical nature of version parsing for the wider Cargo ecosystem.

Code Quality The crate has a dedicated tests/ directory alongside fuzz targets specifically exercising the parser against malformed input, an important quality bar given that this crate underpins Cargo’s own dependency resolution. Code is organized into small, single-responsibility modules (identifier.rs at 412 lines is the largest besides lib.rs), and the specialized Identifier type in identifier.rs shows deliberate attention to avoiding unnecessary allocations in a hot-path parsing library.

API Design The public API is small and idiomatic: Version::parse(&str) and VersionReq::parse(&str) return Result types, and VersionReq::matches(&Version) is the primary evaluation entry point, requiring no configuration to get started. Because it mirrors Cargo’s own internal version-handling exactly, the API surface is intentionally unsurprising to any Rust developer already familiar with how Cargo.toml dependency version constraints behave.