What is Hyrum's law?
Engineering culture
Hyrum's law says that with enough users of an API, every observable behaviour of that system will be depended on by somebody, whether or not it was promised in the contract. Named after Hyrum Wright, it is a warning about hidden compatibility. In software, the real interface is often wider than the documented one, because users lean on ordering, timing, formatting, quirks, and even bugs.
What this means
An API is the agreed way one piece of software talks to another, or the way developers call a library or service. In theory, the API contract tells everyone what is safe to rely on. In practice, people also rely on whatever they can see. If a list always comes back in a certain order, someone will assume that order matters. If an error message always has a certain shape, someone will parse it.
That is Hyrum's law. It says popularity creates accidental promises. The more users a system has, and the longer it lives, the more likely it is that some tiny behaviour has become part of somebody's workflow.
So when engineers say "this is just a harmless clean-up", Hyrum's law asks a rude but useful question: harmless to whom?
Why it matters
Hyrum's law matters because it explains why "small changes" can cause outsized anger. A maintainer may think they are changing an internal detail. A customer, colleague, or downstream team may experience that same detail as part of the product.
That has practical consequences for product teams, platform teams, and anyone running internal tools. It affects release planning, deprecation, versioning, customer communication, migration budgets, and the emotional heat around bug fixes. What looks like tidying from one side can feel like sabotage from the other.
For leaders, the law is a reminder that compatibility is a relationship, not a declaration. You do not get to decide unilaterally what people depend on. You can choose what you promise. You cannot choose what they notice.
How it works
Where the term came from
Hyrum's law is named after software engineer Hyrum Wright. He described it as an observation from working on large scale library and infrastructure changes in a very large codebase. On his own site, he framed the broader idea as the "law of implicit interfaces". In other words, systems grow a shadow contract made from actual usage, not just from documentation. Titus Winters later helped popularise the shorter name "Hyrum's law" through Software Engineering at Google.
That origin matters because it keeps the term precise. This is not a general complaint that users are awkward. It is a specific observation about how interfaces and implementations blur together when many people rely on a system over time.
What counts as observable behaviour
The obvious cases are documented return values, method names, and published fields. But Hyrum's law is about everything else as well.
Observable behaviour can include the order of items in an otherwise unordered response, the exact text of an error, whether retries happen quickly or slowly, whether duplicate values are preserved, whether whitespace changes, how long a request normally takes, whether identifiers look random, whether an edge case quietly succeeds, or whether a bug has become useful to somebody. If it is visible, somebody can build on it.
This is why the law often feels slightly irritating. It widens the field of responsibility. It says that maintainers are not only maintaining code. They are maintaining habits that users have formed around the code.
Software Engineering at Google gives a memorable example with hash ordering. Most engineers know that a hash-based container should not be treated as a stable ordered list. But if the implementation happens to yield a predictable order, some code will rely on that order anyway. Then a perfectly sensible internal improvement becomes a breaking change in disguise.
Why scale makes the problem worse
If ten people use your system, accidental dependencies may be rare and manageable. If ten thousand use it, the weird cases arrive. One team uses timing as a backdoor signal. Another parses an error string. Another assumes that a "random" order stays the same between releases. Another quietly depends on an old bug because their own code adapted around it years ago.
Scale does not merely increase the number of users. It increases the number of experiments users run against your interface, knowingly or not. Over time, their collective behaviour maps the implementation more fully than the docs ever could.
That is why deprecation is so hard. Removing a system is not a normal change. It is total change. All the accidental dependencies that were merely annoying during maintenance become full migration blockers.
How teams use the term in real work
In engineering culture, Hyrum's law gets invoked when someone proposes altering a widely used interface and underestimates the blast radius. It is especially common in library maintenance, platform work, developer tooling, data formats, and public APIs.
Healthy teams use the law to shape process, not to freeze everything forever. They add telemetry so they can see real usage. They design deprecation paths. They run canary releases. They publish migration guides. They prefer smaller interfaces because smaller surfaces leak less. They also take docs seriously, even though docs are not enough on their own.
The culture lesson is not "never change anything". It is "assume more of your system is public than you hoped".
Examples
A response order that "nobody" relies on
A platform team changes an internal data structure and an API starts returning items in a different order. The docs never promised an order. But three customer teams were displaying the first item as the default choice, and another team had snapshot tests that assumed the old sequence. The platform team thought it had made an invisible improvement. Hyrum's law replies: it was visible enough.
An error message that becomes an interface
A service returns a slightly different error string after a clean-up pass. Nothing in the formal contract has changed. Then support scripts fail, monitoring rules stop categorising incidents correctly, and one downstream application that used a regular expression on the old message starts behaving strangely. None of that was in the handbook, yet all of it was real.
A bug fix that breaks a cherished workaround
A user interface had a long-standing quirk that power users had quietly woven into their routines. The bug is fixed. The team celebrates. Then complaints arrive from users who had built speed and muscle memory around the old behaviour. The software is objectively cleaner and subjectively worse, at least for them.
Common misunderstandings
A common misunderstanding is that Hyrum's law means contracts and documentation are pointless. They are not. Clear contracts still reduce confusion and narrow the surface area of accidental dependency.
Another misunderstanding is that the law applies only to public web APIs. It also applies to internal libraries, data files, CLIs, admin panels, developer tools, and user interfaces. If people can observe it, they can depend on it.
A third misunderstanding is that all accidental dependencies are equally important. They are not. Some affect one obscure script. Others affect core customer journeys. The law warns that implicit dependencies exist, not that every one deserves the same weight.
A fourth misunderstanding is that the only hidden dependencies are bugs. Bugs are part of the story, but timing, formatting, ordering, and performance characteristics also count.
A fifth misunderstanding is that the law forbids change. It does not. It says change must be treated as a social and technical migration, not a private refactor with better taste.
Risks and boundaries
Hyrum's law can become an excuse for paralysis. Teams can wave it around as if every interface must remain frozen forever. That is not sustainable. Software that cannot change is software that accumulates risk, clutter, and cost.
It can also become a smug way of blaming users for depending on the wrong thing. That misses the point. Users generally do not wake up trying to violate your architecture. They follow observable behaviour because observable behaviour is what software gives them.
The good version of Hyrum's law encourages humility and better change management. The bad version becomes fatalism. It turns compatibility into a spooky force of nature and lets maintainers off the hook for poor design, poor signalling, or poor migration support.
The boundary is this: you cannot prevent every implicit dependency, but you can reduce the number, shrink the interface, observe real usage, and roll out change more intelligently. The law is a warning label, not a surrender note.
What to do next
If Hyrum's law feels familiar, begin by deciding which behaviours you truly want to support over time. Make the explicit contract smaller and clearer. Ambiguous interfaces invite accidental reliance.
Then invest in visibility. Telemetry on which fields, endpoints, options, and behaviours are actually used is gold. Without it, maintainers are guessing blind about what is safe to change.
When change is necessary, stage it. Warn first. Provide a migration path. Canary it. Watch who breaks. If possible, preserve old and new behaviour in parallel long enough to learn where the hidden dependencies live.
Finally, teach teams that "private implementation detail" is an aspiration, not a guarantee. In mature systems, compatibility work is not bureaucracy. It is part of the product.
FAQs
What is an API in plain English?
It is the published way software exposes functions or data to other software, or to developers using a library, service, or tool.
Is Hyrum's law only about bugs?
No. Bugs matter, but so do ordering, formatting, timing, defaults, and many other visible behaviours that users may quietly rely on.
Does the law apply to user interfaces too?
Yes. Buttons, shortcuts, quirks, and visual flows can all become de facto contracts once enough people build habits around them.
If every observable behaviour matters, how can software ever improve?
By changing with care: instrument usage, communicate early, provide migration routes, and accept that compatibility work is part of maintenance.
How is Hyrum's law different from Law of leaky abstractions?
Leaky abstractions says hidden complexity eventually shows through a layer. Hyrum's law says users will depend on whatever they can observe, including those leaks.
Is Hyrum's law mainly a big company problem?
Big companies feel it sharply, but any popular product, library, or internal tool can run into it once usage spreads and habits form.