What is a CRDT? Conflict-free replicated data types explained
A CRDT is a data type that copies can edit independently and always merge to the same state. How CRDTs work, why local-first apps use them, with Python code.

A CRDT (conflict-free replicated data type) is a data structure designed so that many copies of it can be edited independently, offline and in any order, and still be merged automatically into the same final state without coordination or a central server picking a winner. It works because the merge operation is mathematically constrained: it is commutative, associative and idempotent, so the order and number of times updates arrive does not matter. CRDTs are the engine behind collaborative editors and “local-first” apps that work offline and sync later.
Where do CRDTs come from?
The formal treatment is Conflict-free Replicated Data Types by Marc Shapiro, Nuno Preguiça, Carlos Baquero and Marek Zawirski, published at the SSS symposium in 2011, with a longer companion INRIA technical report. The abstract states the problem plainly: eventual consistency lets “any replica accept updates without remote synchronisation,” but “published EC approaches are ad-hoc and error-prone.” The paper’s answer was a set of sufficient conditions for convergence, and a name for data types that meet them.
The key definition is strong eventual consistency (SEC). Plain eventual consistency says replicas converge if updates stop. SEC is stronger: “Correct replicas that have delivered the same updates have equivalent state.” No rollback, no consensus round, no “conflict detected, please resolve.”
How do CRDTs work?
The paper gives two styles, and proves they are equivalent.
State-based (CvRDT). Each replica periodically sends its whole state to others, which merge it in. The condition for convergence is that the states form a join semilattice and merge computes the least upper bound. In practice that means merge is:
- commutative: merging A into B equals merging B into A,
- associative: grouping does not matter,
- idempotent: merging the same state twice changes nothing,
and every local update only moves state “up”. Theorem 1 of the paper: “any state-based object that satisfies the monotonic semilattice property is SEC.”
Operation-based (CmRDT). Replicas send operations instead of state, over a channel that delivers each one exactly once in causal order. The condition is that “all its concurrent operations commute.” Op-based messages are smaller; state-based replication tolerates a sloppier network.
The simplest example in the paper is a counter. Each replica keeps a vector with one slot per replica and only increments its own slot. Merge takes “the per-index maximum.” The value is the sum of the vector. That is a G-Counter (grow-only). For a counter that also decrements, the paper pairs two of them, I for increments and D for decrements, and the value is the difference. That is a PN-Counter.
What does a CRDT look like in code?
Here is the paper’s counter construction in Python, standard library only. Three devices edit a counter while offline, then sync. First the naive approach, where the last value written wins; then the CRDT merge, tried in all six possible orders with a duplicate delivery thrown in.
# crdt_counter.py: a state-based G-Counter and PN-Counter (Shapiro et al., 2011), stdlib only.
import copy
from itertools import permutations
class GCounter:
def __init__(self, n, i): self.v, self.i = [0] * n, i
def inc(self, k=1): self.v[self.i] += k # each replica bumps only its own slot
def value(self): return sum(self.v)
def merge(self, other): # least upper bound: per-index max
self.v = [max(a, b) for a, b in zip(self.v, other.v)]
class PNCounter: # two G-Counters: value = |I| - |D|
def __init__(self, n, i): self.p, self.n = GCounter(n, i), GCounter(n, i)
def inc(self, k=1): self.p.inc(k)
def dec(self, k=1): self.n.inc(k)
def value(self): return self.p.value() - self.n.value()
def merge(self, o): self.p.merge(o.p); self.n.merge(o.n)
# Three devices edit offline: a "likes" counter on a phone, a laptop and a tablet.
phone, laptop, tablet = (PNCounter(3, i) for i in range(3))
phone.inc(3); laptop.inc(2); laptop.dec(1); tablet.inc(5)
print("local values:", phone.value(), laptop.value(), tablet.value())
# Naive sync: last writer's number wins. Updates from the other devices vanish.
print("last-write-wins:", tablet.value(), "(lost", 3 + 2 - 1, "updates' worth)")
# CRDT sync: merge in every possible order; all replicas end at the same value.
results = set()
for order in permutations([phone, laptop, tablet]):
r = copy.deepcopy(order[0])
for other in order[1:]:
r.merge(other)
r.merge(order[1]); r.merge(order[1]) # duplicate delivery: idempotent
results.add((r.value(), tuple(r.p.v), tuple(r.n.v)))
print("merged in 6 orders ->", results)
Output (Python 3.13.11):
local values: 3 1 5
last-write-wins: 5 (lost 4 updates' worth)
merged in 6 orders -> {(9, (3, 2, 5), (0, 1, 0))}
The set has exactly one element: every merge order, including duplicated messages, produced the value 9 and the same internal vectors. That is strong eventual consistency in one line of output. The naive sync, by contrast, keeps the tablet’s 5 and silently drops everything the phone and laptop did.
Notice the trick. Nobody resolved a conflict, because the data type was designed so conflicts cannot exist. A replica never overwrites another’s slot; it can only learn a bigger number for it.
How do CRDTs handle conflicting edits?
Counters are easy because increments commute. Sets are where design choices appear. The paper walks through it: if one replica adds an element while another concurrently removes it, “the add could win, or the remove could win,” or some other rule, and “all these alternatives satisfy the strong convergence condition.” So “conflict-free” does not mean the system read your mind. It means the conflict policy is fixed in the data type, applied identically everywhere, and needs no coordination.
The paper also points out a consequence that surprises people: SEC “is incomparable to sequential consistency.” With add-wins semantics you can reach a state that no single sequential ordering of the operations would produce. If your invariant needs a global order (a bank balance that must never go below zero, a seat that can be sold once), a CRDT alone will not enforce it.
Text is the hardest case. Collaborative editing needs a sequence CRDT, where each character gets a unique, ordered identifier so concurrent inserts at the same position land in a consistent order on every replica. The SSS paper cites the authors’ earlier Treedoc as one such design. Automerge, the library the Ink & Switch authors built, implements this family.
What is local-first software, and why does it need CRDTs?
Ink & Switch’s essay Local-first software by Martin Kleppmann, Adam Wiggins, Peter van Hardenberg and Mark McGranaghan (April 2019, published at Onward! 2019) argued that the copy of your data on your own device should be the primary copy, and servers should hold secondary copies to help with sync. It lists seven ideals:
- “No spinners: your work at your fingertips”
- “Your work is not trapped on one device”
- “The network is optional”
- Collaboration with your colleagues that needs no manual merging (the essay’s fourth ideal, paraphrased)
- “The Long Now”
- “Security and privacy by default”
- “You retain ultimate ownership and control”
The essay’s reminder about the cloud is a bumper sticker: “There is no cloud, it’s just someone else’s computer.” CRDTs are the enabling technology because they let every device accept writes offline and still converge. The authors describe them as “general-purpose data structures, like hash maps and lists” that are “multi-user from the ground up,” and they built Automerge to test the idea.
Where do CRDTs break?
The Ink & Switch authors were candid about the limits, and I would read their findings before adopting one.
History grows. CRDTs “accumulate a large change history, which creates performance problems.” Deleted items often leave tombstones so a late-arriving operation can still be placed correctly. Memory and disk grow with edits, not with visible content.
Same field, same time. CRDTs merge automatically, but they cannot decide intent when “multiple users concurrently update the same property of the same object.” You get a deterministic answer (often last-writer-wins on that field, or both values kept) that may not be the one a human would pick.
Invariants across objects. A CRDT guarantees convergence, not business rules. Two offline users can each book the last seat. Anything that needs “exactly once” or “never below zero” still needs a coordinator or a compensating action, the kind of orchestration I describe in durable execution.
Networking and auth are still yours. The essay calls the networking part an area that “remains an unsolved problem,” and says of their own libraries: “We do not claim that these libraries fully realize local-first ideals.”
Schema evolution. Old clients keep producing operations in old shapes. Plan for migrations that run on every device, not one database.
What I would do
From a data-platform seat, the question I would ask first is where the source of truth lives. If it is a central database with strong invariants (orders, payments, inventory), I would keep it there and use CRDTs only for the parts users edit together: documents, whiteboards, comments, presence, offline drafts. If the product’s promise is offline work and user ownership, I would make the device the primary copy and pick a maintained library such as Automerge instead of writing a sequence CRDT myself.
In both cases I would budget for compaction of history from day one, decide the concurrent-update policy per field explicitly, and test sync with randomized merge orders and duplicate deliveries, the way the script above does. If you are choosing between this and a server-rendered approach, htmx’s own essay is clear that offline-first is where hypermedia stops working. For analytical data, where the merge unit is a table snapshot rather than an edit, see Apache Iceberg and DuckDB.
FAQ
What does CRDT stand for?
Conflict-free replicated data type. The 2011 paper also uses “convergent” (state-based) and “commutative” (operation-based) for the two variants.
What is the difference between CRDTs and operational transformation?
Operational transformation (OT), used by older collaborative editors, rewrites concurrent operations against each other, usually through a central server. CRDTs make operations or states commute by design, so replicas can merge peer to peer without a server ordering them.
Are CRDTs eventually consistent?
They meet a stronger guarantee, strong eventual consistency: any two replicas that have received the same set of updates are in the same state immediately, with no rollback or conflict resolution step.
What are CRDTs used for?
Collaborative text and whiteboard editors, offline-capable note and task apps, shared counters and sets across data centers, and presence or cursor state in multiplayer apps.
Do CRDTs need a server?
Not for correctness. Replicas can sync peer to peer. In practice a server is still useful for relaying, backup and authentication, as a secondary copy rather than the source of truth.
Sources
- Shapiro, Preguiça, Baquero, Zawirski, Conflict-free Replicated Data Types, SSS 2011, and the INRIA research report RR-7687, 2011
- Kleppmann, Wiggins, van Hardenberg, McGranaghan, Local-first software: you own your data, in spite of the cloud, Ink & Switch, April 2019 (Onward! 2019)