Coq-HoTT for formal homotopy type theory proofs

What Coq-HoTT Formalizes in Rocq

Coq-HoTT develops Homotopy Type Theory inside the Rocq proof assistant, formerly called Coq. Its purpose is not ordinary software verification with types used only as data categories. The library formalizes a setting in which propositional equality has a homotopical interpretation and type isomorphism corresponds to homotopy equivalence. Logical constructions in that setting therefore acquire meaning as homotopy-invariant constructions on spaces.

The intended users are proof engineers, type theorists, and researchers working with univalent foundations. The repository topics identify homotopy-type-theory, type-theory, and univalent-foundations as its subject areas. The README also connects the development to higher category theory and higher toposes, although it does not claim that the entire library formalizes those subjects.

This scope makes Coq-HoTT a research library rather than a general application framework. An adopter needs more than ordinary Rocq experience. The formal statements depend on equality proofs, universe levels, type-level constructions, and the handling of indices. The explicit `-indices-matter` requirement is therefore part of the library's mathematical setup, not a cosmetic build preference.

The project also draws on Vladimir Voevodsky's Foundations library, which the README says was incorporated into UniMath, and on ideas shared with HoTT-Agda. That lineage helps explain its subject, but it does not make the libraries interchangeable. They use different proof assistants and toolchains.

The Argument Model Behind Coq-HoTT

The README describes Homotopy Type Theory as an interpretation of Martin-Löf's intensional type theory into abstract homotopy theory. Within that interpretation, a proposition is associated with a space, equality is interpreted through homotopy, and an isomorphism of types corresponds to homotopy equivalence. A theorem stated in the logic can then be read as a statement about those homotopical constructions.

This interpretation changes what a proof obligation means. A development is not merely checking whether two computational expressions produce the same normalized term. It is working in a formal system where equality carries homotopical content. Consequently, proof structure and the exact theorem statements matter. Ordinary Rocq habits may lead a contributor to overlook assumptions that are significant under HoTT.

Based on the repository layout, the formal content lives under `theories/`, while `etc/generate_coqproject.sh` generates the `_CoqProject` file from the Makefile workflow. The repository also contains `test/`, `contrib/`, `doc/`, and separate Makefiles. This layout separates the library's mathematical development from build generation, documentation, tests, and contribution support.

The generated build model is visible in `Makefile`. Its default target is `invoke-coqmakefile`. That target invokes `rocq makefile` to generate `Makefile.coq`, then forwards the requested target to the generated Makefile. This is a concrete build mechanism, but the README does not enumerate the individual theory modules or describe their dependency graph. Any claim about a specific module's contents would require reading that module itself.

Installing Coq-HoTT Through opam

The README directs users to `doc/INSTALL.md` for detailed installation instructions and states that the library can be installed using `opam`. It does not provide the complete `opam` command, supported Rocq version matrix, or operating-system requirements in the opening README. Consequently, there is no justified installation command to reproduce here.

The concrete first integration step is the project configuration. For use from another Rocq project, the README says to place these arguments in `_CoqProject`:

-arg -noinit
-arg -indices-matter

These arguments tell Rocq to start without its usual initialization and to treat indices as significant during type checking. The second setting is especially consequential for a homotopy library because changes involving indexed families cannot be handled as if indices were irrelevant. Other development methods may work when the same arguments are passed, according to the README.

After adding the arguments, the dependency still has to resolve to the installed HoTT library through the normal Rocq package configuration. The README does not show a complete external `_CoqProject`, an import statement, or a sample theorem, so it would be misleading to invent one. For a first real use, begin with the installation instructions in `doc/INSTALL.md`, verify that the available Rocq toolchain matches what that document requires, and preserve the two documented arguments in the consuming project.

Building, Documentation, and Contributor Checks

The top-level Makefile provides the build entry point rather than asking contributors to maintain `Makefile.coq` by hand. According to the file, `Makefile.coq` depends on `Makefile` and `_CoqProject`. The first dependency runs `bash etc/generate_coqproject.sh`, and the second step invokes `$(COQBIN)rocq makefile`.

For contributors, the repository includes `doc/STYLE.md`, while the README points editors to the recommended list in `doc/INSTALL.md`. It also provides `doc/TIMING.md` for build timing tips. These references matter because contribution work is more involved than opening a theorem file in an editor. The library has explicit style guidance, generated project metadata, tests, and build documentation.

Generated documentation is available through `rocq doc` and Alectryon, with access linked from the project wiki. The README does not give a local documentation command, so none is presented here. Likewise, `doc/TIMING.md` is identified but not reproduced, which prevents a defensible comparison of compile times for different machines or targets.

The repository is not archived, and its last push was on 2026-10-09. Releases include V9.1 on 2026-06-24, V9.0 on 2025-01-31, and V8.20 on 2024-09-27. Those dates indicate recent repository and release activity. They do not establish compatibility for every Rocq release, so an adopter should still check the installed package requirements rather than infer compatibility from release names.

Coq-HoTT Versus HoTT-Agda and Conventional Rocq

The clearest alternative mentioned by the README is HoTT-Agda. The README presents it as an intellectual counterpart rather than as an interchangeable package, but does not provide further technical details about it.

UniMath is another related comparison point. The README says Voevodsky's Foundations development was incorporated into UniMath. UniMath is therefore relevant background and an alternative environment to examine when a project is framed around a large Rocq mathematics library, although the README does not provide enough information to claim feature parity between UniMath and Coq-HoTT.

A conventional Rocq library is a different category of tool. It may rely on Coq's default initialization and ordinary handling of indices, whereas Coq-HoTT explicitly requires `-noinit` and `-indices-matter`. The library is therefore the wrong choice when a project merely wants standard Rocq lemmas and cannot accommodate those settings. It also requires contributors who can reason about the formalization of homotopy and equality, not just developers who want a proof-checking tool.

The wrongness is contextual, not absolute. A team already standardized on Rocq may prefer Coq-HoTT for HoTT proofs. A team committed to Agda may find HoTT-Agda more direct. A team needing conventional metatheory should first examine what its proof goals actually require.

License, Upgrade Scope, and Adoption Friction

The README identifies the library as released under the permissive BSD 2-clause license and directs readers to `LICENSE.txt`. Its summary says users may do what they like with the library provided they preserve the copyright messages, and it includes a warranty disclaimer. GitHub classifies the license as Other because it uses a custom or nonstandard classification entry, so the actual `LICENSE.txt` file remains the source that an adopter should review. This is a license reading, not legal advice.

Upgrades can affect more than a small local proof. Since equality and indices are central to this formal setting, changes in Rocq, library organization, or proof dependencies may require more than editing an import list. The repository has a generated `_CoqProject`, generated build Makefile, tests, style guidance, and timing documentation. Those components indicate that library work includes build metadata and validation, although the repository files do not quantify upgrade effort.

The recent releases provide concrete integration milestones, but release names alone do not describe migration procedures. The README does not document a compatibility matrix or a rollback process. Before adopting a release, an engineering team should inspect `doc/INSTALL.md`, confirm the Rocq version constraints for the selected `opam` package, and review the generated build path for the target environment.

Editorial conclusion

Adopt Coq-HoTT when a project needs homotopy type theory formalized in Rocq and can meet its compiler options, indexing assumptions, and build costs. Do not choose it as a drop-in conventional Rocq library or when the BSD 2-clause terms conflict with your distribution policy. Verify the detailed installation procedure in `doc/INSTALL.md`, the required `_CoqProject` arguments, and the build behavior for your development environment before integrating it.

Frequently asked questions

Official sources

1. HoTT/Coq-HoTT on GitHub
2. Issues
3. Project website
4. README
5. Releases