Lean and Mathlib tooling #
Checking a Lean file that imports Mathlib has two costs: loading the import closure, paid once per process, and elaborating the file, paid per check. For short files the first dominates. A feedback loop that starts a new process per check pays the import every time; one that keeps a process alive pays only elaboration.
import cost #
lake env lean F.lean starts a fresh lean, memory-maps the .olean files of
everything F imports, and then elaborates F. With import Mathlib that load
is several thousand files. On Lean v4.35.0-rc4, three files of a few hundred
lines each measured as:
| idle cloud box | laptop under heavy load | |
|---|---|---|
import Mathlib |
about 8 s | 20–50 s |
| elaborating one file after import | about 2 s | 2.5–11 s |
elaborating example : 1 + 1 = 2 := rfl after import |
0.02 s | 0.01–0.04 s |
The import time moves with disk cache and machine load far more than elaboration does, so it is also the noisy part of any timing.
Importing only the modules a file needs shrinks the load, at the price of
maintaining import lists. For exploratory work import Mathlib plus a warm
process is cheaper.
a warm REPL #
leanprover-community/repl
is a process that reads JSON commands on stdin and keeps environments in
memory. Each command returns an environment id, and a later command can name
the environment it starts from:
{"cmd": "import Mathlib"} → {"env": 0}
{"cmd": "<body of F.lean>", "env": 0} → {"env": 1, "messages": [...], "sorries": [...]}
Commands are separated by a blank line. Environments are immutable, so
checking every file against environment 0 gives each one a clean start: the
import is paid once and each later check costs only its own elaboration.
Replacing the import lines with blank lines before sending the body keeps
the reported line numbers equal to the file's.
Keeping that process behind a unix socket lets separate shell invocations share it. On macOS the socket path must fit in 104 bytes, so bind it by a short relative path, not an absolute one deep in a checkout.
Two limits:
- The REPL sees built modules, not source. A file that imports a sibling
module of the same project is checked against that sibling's last compiled
.olean. Edits to the sibling are invisible until it is rebuilt. - The REPL must match the toolchain. Its repository tags releases by Lean
version (
v4.35.0-rc4); require the tag that equalslean-toolchain.
sorry arrives in a separate sorries array, not as an error message, so a
checker that only counts errors passes unfinished proofs.
the olean cache #
lake exe cache get downloads prebuilt .olean files for the exact Mathlib
revision in lake-manifest.json. Without them lake build compiles Mathlib
from source. lake update runs the same download through Mathlib's
post-update hook and moves lean-toolchain to the one Mathlib uses.
pinning Mathlib #
A [[require]] with no rev follows the dependency's default branch. The
manifest records the commit that was resolved, and lake build uses the
manifest, so builds are reproducible until someone runs lake update. A bare
lake update then moves Mathlib to the head of master, which can change the
toolchain and rename lemmas the project uses.
Writing the commit into the lakefile removes that step from the set of accidents:
[[require]]
name = "mathlib"
scope = "leanprover-community"
rev = "<commit>"
lake update <package> updates one dependency and leaves the others at their
manifest revisions, which is the safe way to add a package to a pinned project.
Moving Mathlib becomes a deliberate edit of rev and lean-toolchain together.
the gate #
The REPL is a feedback loop, not a verdict. lake build compiles every module
in dependency order from source, so it catches what the REPL cannot: a change
in one module that breaks another, and a root file whose imports no longer
resolve. Iterate against the warm process; run lake build before a commit.
sources #
zzstoatzz.io/square-peg—lean/scripts/repl.py,lean/lakefile.toml,lean/README.md; timings taken 2026-10-09 on Leanv4.35.0-rc4.- leanprover-community/repl — command format and version tags.