Skip to main content
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.
1

Observable beats documented

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.
2

Scale turns accidents into requirements

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.
3

Compatibility often means bug-for-bug

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 on tolerance versus strictness.
4

Testing finds dependencies; it does not remove them

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.

Library and API ownership

Document intentional guarantees; hide or randomize incidental ones (for example, hash iteration order) when you must keep freedom to change.

Product and platform changes

Treat screenshots, CSV column order, and webhook payload quirks as de facto APIs for partners and power users—not only for engineers.

Team process and policies

Unwritten “how we always do it” habits become load-bearing like Conway’s Law shapes structure—change the ritual and something silent breaks.

Personal tools and learning

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.
These pages help place Hyrum’s Law among interoperability, system growth, and unintended coupling.

Postel's Law

Tolerance helps interoperate—and can also cement quirks that later become implicit contracts.

Conway's Law

Org structure shapes systems; informal habits similarly shape what people depend on.

Gall's Law

Working complex systems grow from simpler ones—along with accidental surfaces users latch onto.

Goodhart's Law

When a measure becomes a target it warps; when a quirk becomes a dependency it freezes.

Unintended Consequences

Visible side effects become part of the real outcome set for users.

Wirth's Law

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.