Essential Paxos: a readable Paxos implementation kept for study, not for production

The author says his own repository should not be your first choice

The most useful thing in this README is the recommendation against it. The project is described as the results of a first foray into providing both a useful and educational Paxos implementation, in pretty good shape and still filling its intended role, but with one design flaw the author now calls out. The design includes explicit support for sending network messages, and the README states that this is now considered something of an anti-pattern for Paxos implementations, with a recommendation to use an even more tightly constrained library that implements the core algorithm and nothing else, including messaging. Two follow-on repositories are named for that purpose, python-composable-paxos and a multi-paxos-example built on it, and the README says those should generally be preferred over this one. So the honest framing is that this is a reference implementation and a teaching artifact, kept in the state its author found useful, and the code you would actually build on lives next door. The last push to the repository was on 2026-07-21, and the version in the README is v2.0 from January 2013, so the file has been touched far more recently than the implementation itself.

Five modules that peel one algorithm apart layer by layer

The Python side is organised so that each module adds exactly one concern to the one before it, and that layering is the reason the library is worth reading. essential.py is a direct and minimal implementation of the essential Paxos algorithm, and the README is explicit that its primary purpose is educational, because it allows an easy contrast between the pure algorithm and the version enhanced for practicality. practical.py enhances that and adds support for leadership tracking, NACKs and state persistence. functional.py provides a fully functional Paxos implementation that employs a simple heartbeating mechanism to detect leadership failure and initiate recovery. external.py is an enhanced version of practical.py that supports the use of external failure detectors to drive leadership management, and the README is careful to say it does not provide a fully functional solution to leadership management, as functional.py does, though it may serve as the basis for much more flexible, application specific leadership management. durable.py addresses the part most Paxos examples skip, saving Acceptor state to persistent media before Promise and Accepted messages go over the network, so that promises made to external entities are never reneged if the application crashes at an inopportune time. It implements a very simple mechanism for efficiently saving application state to disk.

The design goal is to be independent of the application and the network

The distinguishing characteristic of this implementation, as the README puts it compared with other freely available and open source implementations, is that the library is independent of application domains and networking infrastructures. Whereas most Paxos implementations are deeply and inextricably embedded within application specific logic, this one focuses on encapsulating the Paxos algorithm within opaque and easily reusable classes. That is a design bet, and it has an obvious cost. If the library does not know about your network, then something else has to: the code that wires the message transport in, the code that decides when to start a leader, the code that handles a partition. The project describes itself as providing an algorithmically correct Paxos implementation that may be used for educational purposes in addition to direct use in networked applications, and it says the implementation is specifically designed to facilitate understanding of both the essential Paxos algorithm and the practical considerations that must be taken into account for real world use. Practical here means the awkward parts: leadership failure, recovery after a crash, and the requirement that a promise outlives the process that made it. The clean separation is what makes the library teachable, and it is also why it needs an application around it to be a system.

The Java side mirrors the Python modules package by package

The Java implementation is functionally identical to the Python one and is broken out into Java packages that mirror the Python modules, with the README directing you to the corresponding Python APIs for class and method documentation. The package names make the mapping explicit, with cocagne.paxos.essential, cocagne.paxos.practical and cocagne.paxos.functional listed as the Java entry points. What is absent from that list is telling. There is no cocagne.paxos.durable package and no cocagne.paxos.external, so the two most involved pieces, persistence and external failure detectors, are Python only, which is a real asymmetry if you are evaluating the Java code for production rather than for reading. The repository layout explains the structure. The paxos/ directory holds the Python package, src/ holds the Java sources, and the test/ directory holds the tests. The root also carries .classpath, .project and .pydevproject files, which are Eclipse and PyDev project metadata, so the Java tree was developed in Eclipse and the Python one in a PyDev aware editor. The setup.py at the root packages only the paxos module, which confirms the Python package is the shipped artifact.

Testing the Java code means running it under Jython

The test arrangement is the part of this repository that shows real care, and it is unusual enough to be worth describing precisely. The test directory contains the unittest files used to exercise the implementation. The primary tests are written in Python and correspond to the essential, practical, functional and durable modules. The Java tests, which are also written in Python, wrap the Java classes with a compatible interface and use the Python unit tests to exercise the Java implementation. The result is that the Java code is tested by the same test bodies as the Python code, through a shim, rather than by a parallel Java test suite that could drift. The cost is stated plainly in the README: the Jython interpreter is required for running these tests, but it is not required at runtime. So the Java implementation can be deployed on a normal JVM while its tests need a Python-to-Java bridge. For a library whose whole purpose is to be read and understood, that symmetry is a reasonable trade, and it is the kind of thing you would not find in a project built for production use, where the Java and Python ports would usually be tested separately.

Installing it is a single easy_install command from 2013

The Python installation instruction is one line, and it is a period marker in itself:

$ easy_install essential-paxos

The package name is essential-paxos and the version is 2.0, which the setup.py confirms along with the author, the licence and the description. The setup.py also gives the classifiers, and they are revealing about intent. The development status is listed as 5, Production/Stable, the intended audience is Developers, the operating system is OS Independent, and the topics are System :: Distributed Computing and System :: Networking. Those classifiers describe a library that is complete and portable, not one that is actively evolving. The metadata also confirms the MIT licence. The description in the setup file is a shorter version of the README's claim, describing the package as a Paxos algorithm implementation suitable for practical and educational use. What the installation line does not do is mention Python 3. The README dates from January 2013 and the setup.py imports setuptools._distutils.core, a private module path, which is another sign of the era. Anyone installing this today is likely to hit a packaging toolchain that has moved on considerably, and the README does not document a modern alternative such as pip or a wheel build.

Editorial conclusion

Essential Paxos suits a developer who wants to understand how Paxos actually works, by reading an implementation that separates the core algorithm from the practical additions, and it suits an instructor who needs a reference to hand out. It is the wrong choice for a production consensus system, because the author himself recommends a more tightly constrained library and calls the networking support in this one an anti-pattern. Verify first whether the Java implementation is still what you need, since the source dates from January 2013, and whether the persistence semantics in durable.py match the guarantees your system requires before building on it.

Frequently asked questions

Official sources

1. cocagne/paxos on GitHub
2. Issues
3. License: MIT
4. README