UniMath builds a formal mathematics library on Rocq, package by package

What UniMath is for, and who is expected to read it

UniMath is a library for the Rocq proof assistant, the successor name used here for Coq, and the README states its aim plainly: to formalise a substantial body of mathematics using the univalent point of view. Univalent foundations treat types as sets and equality as paths, which is a different starting point from the set-theoretic picture most mainstream theorem provers assume. A library built on that footing is not a teaching tool and not a general purpose proof toolkit. It is infrastructure for people working in that setting, and the project is candid about the scale of the job it has taken on.

The audience for the documentation is visible in the file layout. Alongside general information there are guides, tutorials, instructions for contributing, and separately generated documentation for two very different ways of reading a proof. The result is a library that expects a reader who already knows what a universe level or a category theory development is, and who wants to check a definition rather than learn a subject.

What the README does not give is an inventory of the mathematics covered. It says substantial body, and the Makefile shows the shape of the effort through its package list, but there is no catalogue in the README mapping topics to packages. If you need to know whether a specific subject is formalised, the answer lives in the source tree and the generated documentation, not in the landing page.

Twenty four packages built in a fixed dependency order

The Makefile is the clearest statement of the library's structure, and it opens with a comment that the packages are listed in order by dependency. The list starts at the bottom of the stack and works upwards:

PACKAGES += Foundations
PACKAGES += MoreFoundations
PACKAGES += IdentitySystems
PACKAGES += Combinatorics

The full sequence runs from Foundations and MoreFoundations through IdentitySystems, Combinatorics, Algebra, Tactics and NumberSystems, into SyntheticHomotopyTheory, PAdics, OrderTheory, CategoryTheory, ModelCategories, Bicategories, Ktheory, Topology, RealNumbers, SubstitutionSystems, Folds, HomologicalAlgebra, AlgebraicGeometry, Paradoxes, Induction, AlgebraicTheories and Semantics. That ordering is not decoration. The build target compiles them in that sequence, so a change in a foundational package forces a rebuild of everything above it.

The order is policed. The Makefile defines a sanity-checks target made of check-prescribed-ordering, check-listing-of-proof-files, check-for-change-to-Foundations and check-for-submodule-changes, and a separate other-checks target holds check-max-line-length. A target named check-for-change-to-Foundations tells you that editing the foundation layer is treated as a special event rather than a normal commit, and check-for-submodule-changes reflects the fact that the repository carries external dependencies in subdirectories.

Resource limits are also part of the build configuration rather than left to the machine:

BUILD_COQ ?= no
BUILD_COQIDE ?= no
DEBUG_COQ ?= no
COQBIN ?=
MEMORY_LIMIT ?= 2500000
LIMIT_MEMORY ?= no

The default MEMORY_LIMIT of 2500000 with LIMIT_MEMORY off, and the separate switches for building Coq itself and the Coq IDE, tell you that this is a heavy build with a compiled proof assistant in the loop rather than a library you drop into a project with one line.

Where installation is documented, and who to ask when it fails

The README deliberately does not contain a command sequence. It points to the documentation directory, where setup/Setup.md holds the install instructions, and it names the other entry points in the same sentence: general information in documentation/unimath/About-UniMath.md, guides in documentation/guides/Guides.md, tutorials under documentation/guides/tutorials, and the contributing guide at documentation/contributing/Contributing.md.

The repository root shows the toolchain the project expects. There is coq-unimath.opam, which is the opam package definition for the library, a dune-project file, a _CoqProject listing the sources for the proof assistant, and a Makefile that drives the whole build. The presence of dune-project alongside the hand written Makefile tells you the library moved toward dune for the build system without giving up the older entry point, and a .gitmodules file confirms that parts of the tree are git submodules, which is consistent with the submodule change check in the sanity targets.

Support channels are specified by kind of question. Questions about the library and requests for help with installing or using it go to the UniMath Zulip, with a registration link, and the README separates those from bugs and improvement suggestions, which become issues on GitHub. That division matters for a library of this size, since a build problem and a mathematical correction travel to different places. The project also asks the Coq development team for credit, and notes their support in keeping UniMath compatible with Coq, which is the clearest statement of an external constraint the library does not control.

Two ways to read the proofs: alectryon and rocqdoc

The library publishes generated documentation in two formats, and the README explains the difference by what you can do in each. The alectryon output lets you step through the proofs and view the goals at every step, so it behaves like a proof script rather than a reference. The rocqdoc output is the classic reference layout, where you click an identifier to jump to its definition, and the README uses disp_cat as the worked example, pointing at a category theory file in the generated tree.

Switching between them is a matter of editing the URL, since the two live under the same generated directory and the names mirror each other. For a reader checking whether a definition is what they assumed, rocqdoc is the faster path. For a reader who wants to see why a step type checks, alectryon is the one that shows the goal state, and for a library whose selling point is machine checked derivations, being able to inspect intermediate goals is the feature that matters.

Both are published as static sites under unimath.github.io, and there is a third path for trying things out: a live browser environment linked from the README, with the files from the School on Univalent Mathematics available to run there. That is the lowest commitment way to see whether the library's definitions line up with your own, and it avoids the entire Coq toolchain question.

Directory layout, licences and the cost of staying in step

Beyond the proof sources, the repository holds a documentation tree, a build directory that includes a Makefile-configuration file and a configuration template, LaTeX material, an emacs directory, a util directory and the sub directory for the submodule dependencies. A Zenodo badge gives the library a DOI, which is how a formalisation gets cited when a paper refers to it.

Licensing needs attention before use. The repository metadata reports a custom licence that GitHub cannot classify, and the file is LICENSE.md at the root. The README itself does not restate the terms and does not point to a summary of them, so a team intending to build on UniMath has to read that file directly, and the project publishes a Zenodo record that will not substitute for it.

Maintenance is visible and current. The last push was on 2026-10-11, and the release history uses dated tags rather than semantic versions: v20260603 on 2026-06-03, v20250923 on 2025-09-23 and a release named UniMath 2024-09-23. Dated tags tell you the cadence honestly, and a dated tag also tells you that pinning a version means pinning a proof library whose compatibility with a given Rocq release is a moving target. The README's thanks to the Coq team for keeping UniMath compatible with Coq is the honest way to read that: compatibility is maintained jointly, not guaranteed by this repository alone.

Where UniMath is the wrong choice

The straightforward case against is scope mismatch. If you need to formalise a small theorem about a data structure, a general purpose theorem prover with a large user base and conventional foundations will get you there faster, and it will not ask you to accept a category theoretic worldview first. UniMath is a large foundational development, and the cost of adopting it is not the download but the commitment to that way of formalising.

The second mismatch is operational. The build is a multi package compilation with a memory limit setting, submodules to fetch, and a separate build of the proof assistant available through the BUILD_COQ switch. The sanity checks also make the workflow prescriptive: the ordering of packages is checked, and a change to Foundations is flagged as its own category of change. Contributors are expected to follow the contributing guide and the prescribed structure, which is right for a library of this consistency and wrong for a casual patch.

The third is documentation depth for newcomers. The tutorials exist and the Zulip is open, but the README is a signpost, and a question that the documentation does not answer becomes a chat question rather than a doc fix. If your team wants a library it can pick up and extend without an ongoing relationship with the maintainers, the gap between what UniMath offers and what you need is the real cost of adoption.

Editorial conclusion

Adopt UniMath if your work needs machine checked foundations, you already reason in univalent foundations, and you can live with a library whose README is a signpost rather than a tutorial. Do not adopt it for general proof engineering, for a quick library of algebra, or for anything that needs a documented and stable public API, since the repository offers a documentation pointer, a Zulip channel and a package layout instead. Verify first that your Rocq version is one the library stays compatible with, then read documentation/setup/Setup.md before you touch the Makefile, because the sanity checks enforce a prescribed package order that will reject a reordered tree.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. UniMath/UniMath on GitHub