mathlib4: the Lean 4 mathematics library and how to install it

What mathlib4 is for, and who should depend on it

mathlib4 is the Lean 4 successor to the Lean 3 mathlib. The README describes it as a user maintained library for the Lean theorem prover that contains both programming infrastructure and mathematics, plus tactics that use the former to develop the latter. That sentence is the whole design brief: it is not a standalone application, it is a body of Lean source that other Lean projects import.

The audience is narrow and specific. You are writing Lean 4 proofs, either as a mathematician formalizing a known result or as a tool builder who needs a library of already proved lemmas to stand on. The repository also ships Archive/, Counterexamples/ and Wanted/ directories at the top level, which signal three distinct kinds of content: formalizations kept for reference, counterexample constructions, and open problems the community wants stated or proved. If your work is in Lean 3, this is not the library you want, and the README points Lean 3 users at a separate survival guide instead.

What it is not: a general purpose mathematics library for Python, C++ or JavaScript. The related search phrase "Mathlib Python" is a mismatch, and the README gives no Python bindings. The content is Lean source, consumed by the Lean toolchain.

How mathlib4 is structured: Mathlib.lean, Lake and precompiled olean files

The repository layout tells you most of the architecture. Mathlib/ holds the source tree, and Mathlib.lean is the root module that imports it. Lake, Lean's build tool, reads lakefile.lean and lake-manifest.json, and lean-toolchain pins the exact Lean version the library is built against. That pin is the contract: mathlib4 tracks a specific Lean release, and your project has to agree with it.

Building from source is expensive, which is why the cached build path exists. The README instructs contributors to run `lake exe cache get` to obtain precompiled olean files, and warns that skipping this step makes the next step very slow. Those olean files are computed by mathlib4's automated workflow and downloaded rather than compiled locally. The README also documents escape hatches for a corrupted cache: `lake clean` or `rm -rf .lake`, and `lake exe cache get!` which re-downloads cached build files even if they are available locally.

Documentation generation is deliberately separated. The mathlib4_docs repository builds and publishes the API docs, and the README notes that the documentation related dependencies should only be included when CI is building documentation, which is why it asks contributors not to run `lake update -Kdoc=on`. Continuous integration runs through Bors, and the README links a DownstreamTest directory, so changes are checked against projects that depend on mathlib4 rather than only against mathlib4 itself.

Installing mathlib4 and running a first build

The README does not inline the installation steps. It points to the community get started page for detailed instructions covering Lean, mathlib and supporting tools, and offers a GitHub Codespace containing the project as an alternative for readers who do not want a local toolchain. The contributor workflow below is the one the README documents directly, and it assumes Lean and Lake are already present.

First fetch the precompiled build artifacts. This is the step the README singles out, because without it the subsequent build compiles the library from source.

lake exe cache get

Then build the library. Expect this to produce olean files under the Lake build directory, and to be substantially faster when the cache download succeeded.

lake build

To work on a single file rather than the whole tree, the README gives a path-scoped form. This builds only the module you name and its dependencies.

lake build Mathlib.Algebra.Group.Defs

If you add a new file, the README says to regenerate the root module with the following, which updates Mathlib.lean so the new file is reachable from the library root.

lake exe mk_all

Running `lake test` builds and runs all tests. The README also documents building the HTML documentation locally by cloning mathlib4_docs, copying the lean-toolchain file into it, running `lake exe cache get`, and then `lake build Mathlib:docs`, noting that the last step may take more than twenty minutes and that the output lands in `.lake/build/doc`.

Where mathlib4 will cost you: build time, version pinning and scope

The most concrete limitation is already in the README: skipping the cache download makes the build very slow. That is not a throwaway warning. mathlib4 is a large Lean codebase, and compiling it from source is a long operation even on capable hardware. The cache exists because the from-source path is impractical for routine work.

Version pinning is the second constraint. The repository carries a lean-toolchain file, and mathlib4 tracks Lean releases; the recent tags in the repository are release candidates and releases like v4.35.0-rc2 and v4.34.0, which indicates a fast moving target rather than a frozen one. A project pinned to an older Lean version cannot simply take the newest mathlib4. The README addresses dependency updates for contributors, telling them to use `lake update` or a targeted form such as `lake update batteries aesop` and to commit the resulting lake-manifest.json in a pull request.

The third limitation is scope. The README links a page of currently covered theories, and that phrasing matters. Coverage is uneven across mathematics. Probability and measure theory appear in the maintainer list, as do algebra, number theory, algebraic geometry, category theory, topology, functional analysis and calculus. If your area is not on the theories page, you are writing the definitions and lemmas yourself, and the library will not save you the work. There is also a contribution process with a style guide, a naming convention and a documentation style, so upstreaming your work is a review process, not a push.

Alternatives: mathlib4 versus a Lean 3 mathlib or a general purpose library

The honest alternative is not another Lean 4 library, because mathlib4 is the community library for Lean 4. The real fork in the road is which proof assistant and which library generation you commit to.

If you have existing Lean 3 formalizations, the README points to a Lean 4 survival guide and to mathport, the tool the community used to port the entirety of mathlib from Lean 3 to Lean 4. That is a migration path, not a parallel library. Running mathport on a project other than mathlib is documented, and it is the difference between rewriting proofs by hand and mechanically translating them. The trade-off is that a ported codebase still needs review against Lean 4 conventions.

If your goal is numerical computation, data analysis or symbolic manipulation outside a proof assistant, mathlib4 is the wrong category of tool entirely. It has no Python interface, and the related searches for a Mathlib Python package or a Mathlib download in the sense of a binary release do not correspond to anything the README describes. There is no compiled artifact you install and call; you consume Lean source through Lake. Choosing mathlib4 means choosing to work inside Lean's type theory and tactic language, with all the proof obligations that entails.

Licence, maintenance and the cost of keeping up

mathlib4 is Apache-2.0. For most users that is permissive enough to depend on and to build on, including in commercial settings, but the repository also carries a CITATION.md and a CODE_OF_CONDUCT.md, and contributions are governed by the community guide rather than by a single owner. If you plan to redistribute a modified copy or embed it in a product, read the licence text yourself; this article is not legal advice.

The repository is not archived, and the last push was on 2026-09-23, so the codebase is being changed continuously. That cuts both ways. You get fixes and new mathematics without waiting, and you inherit churn. The maintainer list in the README assigns areas to named people, which is useful when you need to know who reviews a change in your field, but it also means review capacity is finite and concentrated.

The upgrade cost is real and is mostly about the toolchain pin. Because mathlib4 follows Lean releases, moving to a newer mathlib4 generally means moving your own project to a newer Lean, and re-checking anything that depended on changed names or changed tactic behaviour. The naming and style guides exist precisely to keep that churn manageable, but they do not eliminate it. Budget for periodic dependency bumps rather than a one-time install.

Editorial conclusion

Adopt mathlib4 if you are proving mathematics in Lean 4 or building tactics on top of an existing body of formalized results; do not adopt it as a general purpose numeric or symbolic library for Python, C++ or JavaScript, because its content is Lean source and its build system is Lake. Before committing, verify that your lean-toolchain matches the revision mathlib4 expects, that lake exe cache get succeeds for your platform, and that the theories page lists the area you intend to formalize.

Frequently asked questions

Official sources

1. leanprover-community/mathlib4 on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases