url

The url crate is Rust’s canonical URL parsing, validation, and manipulation library, implementing the WHATWG URL Living Standard so behavior matches web browsers exactly. Originally developed for the Servo browser engine, it now underpins a huge share of the Rust ecosystem — from HTTP clients like reqwest to web crawlers and CLI tools — with over 743 million downloads.

It ships as a small Cargo workspace of focused crates (url, idna, percent-encoding, form_urlencoded) so each concern — punycode/IDNA conversion, percent-encoding, and form-urlencoded parsing — can be reused independently. The core Url type supports zero-copy component slicing, relative URL resolution, and optional no_std, serde, and browser-quirks APIs.

What You Get

• A Url type with typed accessors and mutators for scheme, host, port, path, query, and fragment
• A WHATWG-spec-compliant parser tested against the official web-platform-tests URL conformance suite
• Automatic percent-encoding/decoding and IDNA/punycode handling for internationalized hosts
• A no_std-compatible core plus optional serde, expose_internals, and browser-quirks APIs

Common Use Cases

• Parsing and validating URLs from user input or config files
• Resolving relative links against a base URL (crawlers, browsers, package managers)
• Building and normalizing request URLs for HTTP clients
• Comparing or deduplicating URLs by their normalized, parsed form

Under The Hood

Architecture

rust-url is organized as a Cargo workspace that splits concerns into focused, independently-versioned crates: percent-encoding and form_urlencoded handle low-level encoding, idna handles Unicode domain-name conversion (via the ICU4X-backed idna_adapter), and url composes them into the public Url type. Internally, Url stores the serialized string plus a set of byte offsets (see slicing.rs’s Position enum), so components are extracted by indexing into the string rather than allocating substrings. parser.rs (~69KB) implements the WHATWG URL state machine directly against the spec, host.rs models Host as Domain/Ipv4/Ipv6 variants, and quirks.rs layers a second API surface that mirrors the exact JavaScript URL getter/setter semantics used by browser engines. This is a deliberately layered, spec-driven design: change the state machine and everything downstream (Servo, reqwest, thousands of dependents) inherits the fix.

Tech Stack

The crate is #![no_std] with an alloc feature for constrained environments, and a std feature (default) layered on top; serde/serde_derive are optional dependencies gated behind a serde feature flag, and wasm-bindgen-test covers the wasm32 target in dev-dependencies. Sibling workspace crates are pulled in via path dependencies with independent semver (idna 1.1.0, percent-encoding 2.3.2, form_urlencoded 1.2.2), and MSRV is pinned at Rust 1.63. CI (.github/workflows/main.yml) runs cargo test across multiple feature combinations (default, no-default-features --features=alloc, serde+expose_internals), plus cargo fmt --all --check and cargo clippy --workspace --all-targets -- -D warnings.

Code Quality

Test coverage is unusually rigorous for a crate of its size: tests/wpt.rs runs a custom harness against tests/urltestdata.json, the official WHATWG web-platform-tests URL conformance suite, plus a dedicated setters_tests.json for component-mutation behavior. Nearly every public method in lib.rs (over 100KB, largely doc comments) carries a runnable doctest asserting real parsing behavior, in addition to unit #[test] functions across the workspace. CI enforces formatting and clippy -D warnings on every push, and the crate has been actively maintained since 2013 with 1,415+ commits.

API Design The public API centers on a single ergonomic entry point, Url::parse, returning a typed Result<Url, ParseError> rather than panicking or returning opaque errors. Components are exposed as zero-copy string slices addressable via the Position enum (&url[Position::BeforePath..]), percent-encoding and IDNA/punycode are handled transparently so callers rarely touch them directly, and the separate quirks module offers a parallel API replicating the JS URL object’s exact behavior for interop scenarios (e.g. Servo’s DOM bindings). The tradeoff is a large, dense lib.rs, but the payoff is an API that composes cleanly with reqwest, serde, and other crates that accept impl Into<Url>-style patterns.