> ## Documentation Index > Fetch the complete documentation index at: https://meta.niceshare.site/llms.txt > Use this file to discover all available pages before exploring further. # Hyrum's Law > Hyrum's Law says that with enough users, every observable API behavior will be depended on by someone. Learn origin, tactics, and limits. **Category**: Laws
**Type**: Software compatibility and API evolution law
**Origin**: Hyrum Wright (observation); named by Titus Winters; popularized in *Software Engineering at Google* (2020)
**Also known as**: Law of Implicit Interfaces; bug-for-bug compatibility **Quick Answer** — **Hyrum's Law** states that with enough users of an API, people will depend on every observable behavior—not only what the docs promise. Documentation draws a line; usage draws a thicker one. The practical move is to treat visibility itself as a contract risk and plan changes for implicit dependencies. ## What is Hyrum's Law? Hyrum's Law is the observation that, given enough users, every observable behavior of a system becomes somebody's dependency—whether or not it appears in the official contract. > With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody. Think of a restaurant menu as the contract and the kitchen's habits as the implementation. Guests may start expecting the same plate size, wait time, and side dish that were never written down. In software, sorting order, error-message text, timing, and even bugs can become load-bearing. At scale, the “private” implementation stops being private: consumers collectively pin the whole surface. ### Hyrum's Law in 3 Depths * **Beginner**: If users can see it, someone will build on it—docs or not. * **Practitioner**: Before changing a library or API, ask what callers may already rely on beyond the documented promise. * **Advanced**: Design for entropy of use—minimize accidental observables, detect breakages with tests, and budget migration cost when the implicit interface must change. ## Origin **Hyrum Wright** articulated the observation while working on large-scale library and infrastructure changes at Google: even “invisible” tweaks to core C++ libraries broke distant systems that had leaned on incidental behavior. He framed the extreme form as the **Law of Implicit Interfaces**—with enough consumers, there is effectively no private implementation, and maintainers often need **bug-for-bug compatibility**. Colleague **Titus Winters** named the idea **Hyrum's Law** and helped spread it inside Google. The 2020 O'Reilly book *Software Engineering at Google* (Winters, Wright, and Manshreck) treats it as a central constraint on long-lived code: change discussions must account for Hyrum's Law the way efficiency discussions account for entropy—you can mitigate it, but you cannot erase it. Wright's public site (hyrumslaw\.com) anchors the canonical wording and links the phenomenon to Joel Spolsky's **Law of Leaky Abstractions**: consumers inevitably notice and depend on what leaks through the abstraction. ## Key Points Hyrum's Law is less a moral rule than a prediction about how large user bases freeze observed behavior. Contracts say what is allowed; usage says what is relied on. Error strings, response field order, cache timing, and default formats become part of the real interface once callers encode them. One consumer depending on a quirk is a bug report. Ten thousand consumers make that quirk a migration project. Popularity does not invent new physics—it multiplies who notices each detail. Fixing a bug can break callers who worked around it. Teams then choose among keeping the bug, shipping dual paths, or paying for coordinated migration—classic tradeoffs next to [Postel's Law](/laws/postels-law) on tolerance versus strictness. Broad automated tests can surface implicit expectations early. They do not dissolve the dependency graph; they only make the breakage cost visible before release. ## Applications Use Hyrum's Law whenever something is shared widely enough that “nobody should rely on that” is wishful thinking. Document intentional guarantees; hide or randomize incidental ones (for example, hash iteration order) when you must keep freedom to change. Treat screenshots, CSV column order, and webhook payload quirks as de facto APIs for partners and power users—not only for engineers. Unwritten “how we always do it” habits become load-bearing like [Conway's Law](/laws/conways-law) shapes structure—change the ritual and something silent breaks. When you script around a spreadsheet's accidental sort or an app's odd export, label that dependency; expect it to fail when the vendor “fixes” the quirk. ## Case Study Python's dictionary ordering shows Hyrum's Law turning an implementation detail into a language promise. In **CPython 3.6** (2016), the compact dict redesign preserved insertion order as an **implementation detail**—useful and visible, but not a language guarantee for all Python implementations. Callers still began writing code that assumed that order in practice. By **December 15, 2017**, after python-dev debate, Guido van Rossum ruled: “Make it so. ‘Dict keeps insertion order’ is the ruling.” **Python 3.7** (released **June 27, 2018**) then declared insertion-order preservation an official part of the language specification, so conforming implementations must keep it. The project chose to *ratify* widespread observed behavior rather than deliberately scramble order and break the ecosystem that had already adapted. The lesson is sharp: once enough users can see a behavior, “it was never promised” is a weak defense; either you absorb the contract or you pay for a forced migration. The boundary note is equally sharp: ratification is one strategy—not always the right one when the accidental behavior is harmful or locks out better designs. ## Boundaries and Failure Modes Hyrum's Law is strongest for **widely shared, long-lived interfaces**. A personal script with two users can change freely; a platform API with millions of clients cannot. It fails as an excuse for **never improving anything**. The law predicts breakage risk; it does not forbid change. It asks you to price investigation, communication, and migration—not to freeze forever. A common misuse is blaming users for “misusing” the API while shipping highly visible, undocumented quirks. Visibility without clarity invites dependency. Another misuse is treating every flake as sacred: some bugs should be fixed with a versioned break and a migration path, especially when they create security or correctness debt. ## Common Misconceptions Clear use separates prediction, blame, and design strategy. No. Clear contracts still reduce accidental coupling and guide honest users. The law says docs alone cannot stop dependency on what remains visible. No. Internal libraries, CLIs, config formats, and even family shared spreadsheets obey the same pattern once enough people build on them. No. Responses include hiding observables, versioning, dual-running, chaos testing of clients, and sometimes promoting a popular behavior into an explicit guarantee—as Python did with dict order. ## Related Concepts These pages help place Hyrum's Law among interoperability, system growth, and unintended coupling. Tolerance helps interoperate—and can also cement quirks that later become implicit contracts. Org structure shapes systems; informal habits similarly shape what people depend on. Working complex systems grow from simpler ones—along with accidental surfaces users latch onto. When a measure becomes a target it warps; when a quirk becomes a dependency it freezes. Visible side effects become part of the real outcome set for users. Software complexity can consume hardware gains—and complexity multiplies observable surfaces. ## One-Line Takeaway Treat every visible behavior as a potential contract—and design, test, and migrate as if someone already depends on it.