rust-lang/polonius: Rust Borrow Checker Analysis Experiments

Why rust-lang/polonius Exists

rust-lang/polonius solves a narrow compiler research problem. It provides a Rust core library that models the borrow check, described by the repository as “an alias-based formulation of the borrow checker.” Its purpose is not merely to accept or reject a Rust source file. The project is designed so developers can experiment with different implementations of the same algorithm and compare their behavior.

That distinction matters for adoption. The repository links to a blog post, a conference talk, and the Polonius book for details about the formulation. It also contains separate `polonius-engine`, `polonius-parser`, `book`, `src`, and `inputs` directories. Based on that layout, the project brings together an analysis engine, input handling, documentation, and examples. It is primarily useful to Rust compiler developers, borrow-checking researchers, and contributors experimenting with analysis rules.

It should not be installed as though it were a command-line Rust compiler. The documented workflow begins by obtaining facts from `rustc`, then runs Polonius against the generated directories. Users who only want rustc to check their crate already have that path through Rust compilation. Polonius is the better fit when the behavior of the analysis itself matters, including its errors, timing, intermediate tuples, or differences between implementations.

The root `Cargo.toml` describes the package as “Core definition for the Rust borrow checker,” version `0.7.0`, and uses the keyword `datalog`. The README does not document the complete relation schema or a stable external API for driving the analysis, so an evaluator should inspect the checked-out source before designing production automation around its internals.

How Polonius Processes rustc NLL Facts

The documented data flow separates analysis from Rust front-end processing. First, rustc emits NLL facts for a source file or crate. Polonius then reads the resulting `nll-facts` directory, whose subdirectories correspond to individual functions. This means the repository does not receive ordinary Rust source as its primary analysis input according to the README. Rust front-end work, including generating the facts, happens before Polonius runs.

The top-level package depends on the local `polonius-engine` crate and uses libraries including `rustc-hash`, `petgraph`, and `log`. The repository also contains `polonius-parser`, listed as a development dependency. Those entries support a codebase organized around analysis and parsing, but the README does not provide enough detail to claim that `polonius-parser` is the component that ingests every rustc fact directory. Developers needing schema-level integration should examine the relevant source and Cargo configuration directly.

The runner can expose progressively more detail. By default, `cargo run` prints timing. The `--show-tuples` option displays results and errors, while `-v` adds intermediate computations. Consequently, the default output is insufficient for judging whether a sample was accepted. A user investigating an apparent contradiction between rustc and Polonius should enable tuple output before drawing a conclusion.

This separation also creates a compatibility boundary. Polonius consumes compiler output from a particular rustc revision, and the repository pins a toolchain through `rust-toolchain`. The README does not publish a compatibility matrix or promise that facts from an arbitrary nightly release will match. That omission makes repository-local verification important, especially because the documented commands require a nightly compiler and an internal rustc option.

Installing Rust and Running the First Repository Input

The README does not provide a standalone installation command because `polonius` is run from its repository. It specifically uses Cargo with the nightly toolchain for its example. Start from a checkout of the project and run this documented example:

cargo +nightly run --release -- -a DatafrogOpt inputs/clap-rs/app-parser-{{impl}}-add_defaults/

The command selects the `DatafrogOpt` analysis with `-a` and passes the path to an example input. The README's example output shows Cargo finishing the release build, followed by the `borrow-check` executable operating on the specified directory. The output shown in the README also includes a directory label and elapsed time.

By default, the runner prints timing rather than the analysis results. To inspect tuples and errors, add the documented `--show-tuples` option to `cargo run`.

The repository does not show the example input path being repeated for that invocation. Supply the input expected by the checked-out CLI as its help output directs. For intermediate computations, the README identifies `-v` as the relevant option and also states that `--help` provides more documentation.

No output, version claim, or performance result can be predicted for a new checkout. The README's displayed completion time belongs to its example and does not establish what another machine or input will produce. First use should therefore be evaluated by checking the selected analysis name, the input directory, and whether result output was explicitly requested.

Generating nll-facts for Your Own Rust Input

Polonius needs compiler-generated input facts before it can analyze a source file. For an individual Rust file, the README documents this command:

rustc -Znll-facts inputs/issue-47680/issue-47680.rs

The `-Znll-facts` option tells rustc to emit the facts required by the subsequent analysis. The README does not document the compiler version associated with the `issue-47680` example beyond the repository's toolchain setup, so use the checked-out `rust-toolchain` rather than assuming a current system compiler will produce the expected representation.

For an entire crate, the README documents using the `#![feature(nll)]` flag and passing the same rustc option through Cargo:

cargo rustc -- -Znll-facts

After generation, the expected output is a `nll-facts` directory with one subdirectory per function. The README illustrates this structure with `{{impl}}-maybe_next/` and `main/`. Those directories are then passed to the Polonius runner.

This two-stage workflow is the most important setup constraint. `-Znll-facts` is a rustc option, not a Polonius flag, and the analysis selection belongs to the later Polonius invocation. Keeping those commands separate prevents a misleading attempt to make one executable consume both source and generated facts at once. The README does not document a manual fact-file format, a conversion service, or a supported schema for replacing rustc generation.

Choosing DatafrogOpt, Naive, or LocationInsensitive

The `-a` option lets a user select among analysis implementations, but they have different purposes. The README presents `Naive` as a readable but slower implementation of the exact rules described in the linked blog post. That trade-off makes it useful when tracing algorithm behavior or checking how the basic rules work. It is less compelling for rapid iteration where execution speed is the main concern.

`LocationInsensitive` offers the opposite trade-off. The README describes it as faster than a location-sensitive analysis, but it may yield spurious errors. An error from this mode therefore cannot automatically be treated as an error that the more precise analysis would report. This is a genuine limitation, not merely a difference in output formatting. The mode can help compare formulations, but users need to understand whether false positives are acceptable for their experiment.

`DatafrogOpt` appears in the documented execution example, but the README does not explain its internal optimization or identify it as the default. The only confirmed default behavior is that `cargo run` prints timing. The selection command must still name the analysis explicitly with `-a` when comparing a particular implementation.

No timing ratio or ranking beyond those statements is documented. The README gives a sample duration for one repository input but does not provide comparative benchmark conditions. Choosing a mode should therefore start with the question being asked: use `Naive` when readability and correspondence with the basic rules matter, or use `LocationInsensitive` when its documented error risk is acceptable. Verify `DatafrogOpt` against the checked-out source and examples rather than inferring semantics from its name.

Repository Activity, Releases, and License Files

The repository is not archived, and the GitHub repository metadata records its last push as 2026-10-02. That date shows recent repository activity, but a push does not by itself establish a release schedule or compatibility guarantee. The only listed engine release is `polonius-engine-v0.13.0`, dated 2021-08-03, while the root package in `Cargo.toml` declares version `0.7.0`. The root package and engine crate therefore need to be treated as separate version identities rather than collapsed into one release number.

Upgrade planning is constrained by the dependency on rustc's fact-generation interface. The README uses `cargo +nightly`, `-Znll-facts`, and the `#![feature(nll)]` flag. It does not document a stable rustc compatibility matrix, a fact-format migration guide, or a rollback procedure. Anyone automating this repository should keep the `rust-toolchain`, generated input fixtures, root `Cargo.toml`, and local `polonius-engine` revision together during verification.

The `Cargo.toml` metadata declares `Apache-2.0/MIT`, and the repository contains `LICENSE-APACHE` and `LICENSE-MIT`. Those files identify the applicable notices. They do not constitute legal advice about combining Polonius with rustc-generated artifacts or other dependencies. License review should use the repository's actual license files and the versions brought into the build.

The project is not archived and was pushed recently, but the release gap means that adoption should not depend on an assumption of frequent packaged upgrades. Changes to the compiler-facing workflow may require direct repository work rather than a package-manager upgrade alone.

Where Polonius Is the Wrong Tool

The clearest wrong-tool case is ordinary Rust compilation. If the objective is to compile a crate and obtain rustc's normal results, the README provides no evidence that running Polonius first improves the workflow. Its documented pipeline asks for compiler facts before analysis and may require a nightly toolchain. That extra stage is justified by research goals, not by a claim that it is required for normal Rust builds.

Polonius is also a poor fit when diagnostic false positives are unacceptable. The README explicitly warns that `LocationInsensitive` may yield spurious errors. A system that automatically blocks code based on that mode could reject valid input for analysis-specific reasons. The documentation does not provide a production integration guide for combining Polonius with rustc diagnostics.

The repository does not document deployment, observability, long-running service operation, or a stable API for accepting facts from arbitrary compiler versions. It also does not document manual rollback or a migration path between fact formats. Those omissions do not prevent local research, but they make the library a poor foundation for an unverified service dependency.

A direct alternative is to rely on rustc's built-in borrow checker for real compilation. The technical difference is scope: rustc performs ordinary front-end and compilation work, while Polonius consumes generated NLL facts to model and compare a borrow-check analysis. For algorithm research, that separation is useful. For a production build pipeline, it adds a fact-generation stage and an analysis engine whose README includes documented precision caveats.

Editorial conclusion

Adopt rust-lang/polonius when researching Rust borrow checking, reproducing analysis runs, or comparing implementations over the same rustc-generated facts. Do not treat it as a complete Rust compiler frontend or a production decision service. Verify first that the repository's pinned toolchain generates the expected `nll-facts` directories, then confirm that the selected analysis has the precision the task requires. `LocationInsensitive` is appropriate only when its documented risk of spurious errors is acceptable.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. rust-lang/polonius on GitHub