Hyrum's Law¶

With enough users of an interface, every observable behaviour will come to be depended upon by someone regardless of the formal contract, so the cost of changing an observable is set by its dependent count, not its documented status.

Version: v4 · 2026-09-28 · History
Domain-specific #: 517
Domain group: Applied Sciences & Engineering
Origin domain: Computer Science & Software Engineering
Subdomain: API Design and Evolution → Computer Science & Software Engineering

Core Idea¶

Hyrum's Law holds that with a sufficient number of users of an interface, it does not matter what the formal contract promises: every observable behaviour will come to be depended upon by somebody, and any change to it — even outside the documented spec — will break someone's code. An interface produces two contracts at once: the published contract of promised behaviours, and the de facto contract of observables users have built dependencies on. Under scale and time the de facto contract approaches the whole observable surface, by enumeration: given enough users, every observable is sampled and depended upon.

How would you explain it like I'm…

Someone Needs Every Squeak

Imagine a toy that always squeaks twice when you squeeze it, even though the box never promised that. If lots and lots of kids play with it, some kid will build a game that needs those two squeaks. Then if the toymaker changes it to one squeak, that kid's game breaks. Hyrum's Law says that with enough users, someone always depends on everything a thing does.

Every Quirk Gets Used

When programmers build a tool for other programs to use, they write down what it promises to do. Hyrum's Law says that once enough people use it, someone will rely on every behavior they can notice, even ones that were never promised, like the exact wording of an error message or the order things come out in. So if you change any of those behaviors, some user's program will break, even if you kept every promise. That's why careful programmers try to hide or shuffle details people shouldn't depend on, so nobody starts relying on them.

Every Behavior Becomes a Contract

Hyrum's Law, from Hyrum Wright and popularized in the book Software Engineering at Google, says that with enough users of an interface, every observable behavior will be depended on by somebody, no matter what the official contract promises. So an interface really has two contracts: the published one, and a de facto one made of everything users have noticed and built on. With enough users and time, the de facto contract grows toward everything you can observe: error text, ordering of results, timing, edge cases and side effects. People come to rely on these on purpose, by accident, or because there was no documented alternative. The lesson is that shrinking what can be observed, by hiding details or randomizing things like iteration order, matters as much as keeping promises.

Hyrum's Law, formulated by Hyrum Wright and popularized in Software Engineering at Google (2020), states that given enough users of an interface, all observable behaviors will be depended on by someone regardless of the formal contract. Structurally, every interface carries a published contract (promised behaviors) and a de facto contract (observed behaviors users have built on). The de facto contract is always a superset of the published one and, with scale and time, approaches the whole observable surface: error message text, iteration order, timing, edge-case handling and undocumented side effects. The mechanism is enumeration under scale: a large, diverse user base samples every observable property, and some users bake those properties into production code deliberately, accidentally (e.g. tests asserting byte-exact serialization), or for lack of a documented alternative. Consequently, any change to an observable, promised or not, incurs compatibility cost proportional to the number of dependents. The practical discipline is to minimize observable surface, not just contractual surface, through encapsulation, indirection, timing jitter and proactively randomized iteration order.

Cross-Domain Echoes¶

See how this entry connects to another domain.

When yesterday’s choices become today’s constraints

Scope of Application¶

Hyrum's Law lives across the subfields of software and computing where an interface accrues many users over time — one substrate, the kind of observable changing but the mechanism constant.

API and protocol design — the canonical case; Torvalds' "we don't break userspace," down to preserving syscall bugs.
Library and SDK evolution — even unpublished helpers acquire dependents.
Compiler and language design — undefined behaviour and quirks hardening into de facto semantics.
Cloud and platform engineering — provisioning timing, error formats, and quotas ossifying into contracts.
Open-source dependency ecosystems — transitive imports amplifying the effect along every chain.

Clarity¶

The law separates the published contract, the observable behaviour, and the de facto contract — three nested sets — so most "that was never part of the API" disputes dissolve once a team locates which layer a dependency lives in. It replaces the belief that contractual status governs change cost with a sharper rule: cost is set by dependent count, making minimising the observable surface a discipline distinct from minimising the contract.

Manages Complexity¶

Interface evolution presents a pile of distinct headaches — legacy lock-in, dragging deprecations, ossified undocumented behaviors. The law compresses that to three nested sets and one cost rule, so the maintainer reads outcomes off two parameters (population size and diversity, observable exposure), and the safe-versus-breaking question reduces to: is this observable inside the de facto contract?

Abstract Reasoning¶

The law supports a predictive-under-scale move (large diverse base implies the de facto contract approaches the full surface), a diagnostic replacing contractual status with dependent count (telemetry as the decisive instrument), and an interventionist move with a sharp inert-versus-effective split (shrinking the contractual surface is inert; shrinking the observable surface via encapsulation and jitter prevents dependencies forming).

Knowledge Transfer¶

Within software Hyrum's Law transfers as mechanism across every software substrate — the nested sets, cost rule, and inert-versus-effective remedy carry intact. Beyond it the underlying compound recurs as co-instances (customary law, linguistic descriptivism, infrastructure co-option, biological spandrels), but that reach belongs to the compound it instantiates — Path Dependence through observability under scale-driven dependency formation — not the name. It is distinct from Network Effect (value not constraint), the Postel principle (accept not observe side), and adjacent to Goodhart's Law.

Relationships to Other Abstractions¶

Current abstraction Hyrum's Law Domain-specific

Parents (2) — outgoing typed relations

Hyrum's Law presupposes Observability Prime

Hyrum's Law presupposes observability because only behaviors exposed to users can be sampled, depended upon, and converted into a de facto contract.
Hyrum's Law is a decomposition of Path Dependence Prime

Hyrum's Law is the software-interface form of path dependence, where accumulated reliance on historically observable behavior constrains later changes regardless of the published contract.

Hierarchy paths (4) — routes to 4 parentless roots

Hyrum's Law → presupposes Observability

Show alternative paths (3)

Neighborhood in Abstraction Space¶

Hyrum's Law sits in a sparse region of the domain-specific corpus (79^th percentile for distinctiveness): few abstractions share its structure, so a faithful description tends to retrieve it precisely.

Family — Unclustered & Miscellaneous (2769 abstractions)

Nearest neighbors

Computed from structural-signature embeddings · 2026-10-25