# Aquascope: interactive visualizations of Rust ownership and borrow checking

> Aquascope is research software from Brown University's Cognitive Engineering Lab that renders Rust programs as step-by-step diagrams of the borrow checker and the interpreter. It ships as an mdBook preprocessor, which shapes both who can use it and how much setup it costs.

**cognitive-engineering-lab/aquascope** — Interactive visualizations of Rust at compile-time and run-time

- Repository: https://github.com/cognitive-engineering-lab/aquascope
- Website: https://cel.cs.brown.edu/aquascope/
- Stars: 3,172 · Forks: 79
- Language: Rust
- License: MIT
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/cognitive-engineering-lab-aquascope

## What Aquascope visualizes that rustc errors do not

A borrow-checker error tells you a program is rejected. It does not show the sequence of borrows, moves and liveness regions that produced the rejection, and it does not show what the same program does at run time when it compiles. Aquascope's stated purpose is to generate interactive visualizations of Rust programs that show how the borrow checker reasons about a program and how the program actually executes. The README points to a live demo and to an ownership chapter in the Rust Book Experiment as the place to learn what the diagram means.

The audience is narrow and specific. This is teaching and documentation material, not a debugging tool for production code. The README labels the project research software and asks for contributions when bugs appear, which is an honest description of its maturity. The repository layout confirms that framing: there is an ARCHITECTURE.md, a crates directory, a frontend directory, and a Makefile.toml, and the workspace Cargo.toml pins rustc_plugin and rustc_utils to a nightly-2026-05-01 build. Anything that consumes compiler internals at that level is tied to a toolchain, and that tie is the central cost of using it.

## How the mdBook preprocessor and the interpreter fit together

The supported integration path is mdBook. You enable the preprocessor in book.toml and then write code blocks tagged aquascope, and the preprocessor replaces those blocks with generated diagrams in the built book. The README states plainly that further documentation on the syntax and configuration of Aquascope blocks will be provided once the interface is more stable, so the block syntax is the part of the surface most likely to move under you.

Underneath, there are two distinct things being shown. One is a static analysis of the borrow checker's view of the program. The other is execution, and that path goes through Miri: the README calls miri setup a necessary prerequisite to running the Aquascope interpreter. That is why the install instructions pull in the rust-src, rustc-dev, llvm-tools-preview and miri components for a specific nightly. The visualization is not a reimplementation of Rust semantics; it is driven by the real compiler and the real interpreter, which is what makes it credible and also what makes the toolchain pin unavoidable.

## Installing mdbook-aquascope and cargo-aquascope

The README gives a four-command install. The first line installs the preprocessor from crates.io at a pinned version. The next three install a nightly toolchain with the components Aquascope needs, install the frontend from git at a matching tag, and run Miri's setup step.

```bash
cargo install mdbook-aquascope --locked --version 0.3.7
rustup toolchain install nightly-2024-12-15 -c rust-src -c rustc-dev -c llvm-tools-preview -c miri
cargo +nightly-2024-12-15 install aquascope_front --git https://github.com/cognitive-engineering-lab/aquascope --tag v0.3.7 --locked
cargo +nightly-2024-12-15 miri setup
```

Two details matter here. The README notes that cargo-aquascope is installed via aquascope_front and must be installed via git with a specific nightly toolchain, so you cannot substitute a crates.io install for the frontend. And the version pinned in the README, 0.3.7, is not the newest release listed in the repository, which is v0.4.0 dated 2026-05-04. The README's install block has not been updated to that tag, so treat the pinned commands as the documented path and check the release notes before moving to v0.4.0.

If you prefer to build from source, the README requires two extra tools first: cargo-make, installed with cargo install cargo-make --locked, and Depot, installed by piping its install script to sh. After cloning the repository you run cargo make install-mdbook. That path exists but adds a JavaScript build tool to a Rust project, which is a real dependency increase over the four-command route.

## A first Aquascope block in an mdBook

Once the binaries are installed, enabling the preprocessor is a two-line addition to book.toml. The README shows exactly this:

```toml
# book.toml
[preprocessor.aquascope]
```

Then you add a fenced block tagged aquascope,interpreter to a Markdown source file. The README's example uses backtick pairs inside the code to mark the points in the program that the diagram should annotate, and hides the surrounding main function from the rendered output with a leading hash:

```aquascope,interpreter
#fn main() {
let mut s = String::from("hello ");`[]`
s.push_str("world");`[]`
#}
```

Build the book with mdbook build and the preprocessor should replace that block with an interactive diagram. What you should see is the program's state at each marked point, not just the final output. The README does not document the full set of block options, the meaning of the backtick markers beyond the example, or a rollback procedure if the preprocessor fails mid-build, so budget time for reading the source when something does not render.

## Where Aquascope is the wrong tool

The most obvious limitation is the toolchain. Aquascope depends on rustc internals through rustc_plugin and rustc_utils at a specific nightly, and the README's install commands name nightly-2024-12-15 while the workspace pins a nightly-2026-05-01 build. Either way you are on a nightly, and you are on a nightly that the project has chosen. If your organization builds only on stable, or if you cannot install rustc-dev and llvm-tools-preview components, the interpreter half of Aquascope is out of reach.

The second limitation is scope. Aquascope renders code blocks in an mdBook. If what you want is to paste an arbitrary crate into a web page and watch it run, that is not what this is; the README describes a preprocessor and a demo, not a general service. There is also no documented rollback or degraded mode: the README says that if you have trouble finding relevant information you should open an issue or email the maintainers, which is a support channel rather than a troubleshooting guide. The README also warns that Aquascope is research software, so a bug in the visualization is a plausible outcome rather than an edge case.

A quieter constraint is the release cadence. The last push to the repository was on 2026-05-04, and v0.4.0 was tagged the same day. That is roughly four and a half months before today, so the project is not in a state you should describe as under active development right now; plan for the possibility that a question you file sits for a while.

## Aquascope compared with reading the Rust Book or running Miri directly

The practical alternative for most readers is the Rust Book's ownership chapter, which explains the same concepts in prose and is the source Aquascope's own README links to for interpreting its diagrams. The difference in approach is that prose describes a category of error and a diagram shows one concrete program's borrows and moves at named points. If your readers already understand ownership, the book is cheaper: no toolchain, no preprocessor, no nightly. If they keep nodding at the prose and then failing to predict which line the compiler rejects, the diagram is the part that closes the gap.

The second alternative is running Miri yourself on a test, which gives you undefined-behavior detection without any visualization. That is the right tool when your question is whether code is sound, not why the borrow checker rejected it. Aquascope's interpreter exists to show execution state, and Miri is the engine behind it, so choosing Miri directly means giving up the diagram and keeping the diagnostic.

A third comparison is to any hand-drawn ownership diagram in a blog post. Those are static images. Aquascope's blocks are interactive and generated from the code you wrote, which means they stay correct when the code changes, at the cost of the build-time dependency described above.

## Licence, citation and the cost of keeping it running

The workspace declares MIT for the project, and the repository carries a LICENSE file at the top level. MIT is permissive, so embedding generated diagrams in your own book does not create an obvious licensing problem, but the citation section is worth reading before you publish. The README asks that Aquascope be cited if you use it as part of your research, and it supplies a BibTeX entry for the OOPSLA2 2023 paper A Grounded Conceptual Model for Ownership Types in Rust. That is a request, not a licence term, and it applies to research use in particular. None of this is legal advice; if you are shipping a commercial course, read the LICENSE file itself rather than this summary.

The upgrade cost is the part people underestimate. Because the frontend installs from a git tag and the workspace pins rustc_plugin and rustc_utils to a nightly, moving from the README's 0.3.7 to v0.4.0 is not a version bump you can assume is transparent. The README's own install block still names 0.3.7, and the release notes are the place to check what changed. If you embed Aquascope blocks in a book that is built in CI, pin the toolchain in rust-toolchain.toml as the repository does, and expect to revisit that pin when you upgrade.

## Conclusion

Adopt Aquascope if you maintain an mdBook and want readers to step through ownership and borrow-checker behavior instead of reading about it; the preprocessor workflow is the supported path. Do not adopt it if you need a general-purpose visualizer for arbitrary crates, a stable-toolchain build, or a Windows-first setup, because the README requires a specific nightly toolchain and miri. Before committing, verify that the pinned toolchain installs on your machine, that mdbook-aquascope version 0.3.7 is the version you want given v0.4.0 exists, and that your book.toml preprocessor section produces diagrams on one real chapter.

## FAQ

### What is Aquascope used for?

It generates interactive visualizations of Rust programs, showing how the borrow checker reasons about a program and how the program executes. The README points to a live demo and to an ownership chapter in the Rust Book Experiment for reading the diagrams.

### How do I install Aquascope for an mdBook?

The README installs the mdbook-aquascope preprocessor with cargo install mdbook-aquascope --locked --version 0.3.7, installs the nightly-2024-12-15 toolchain with the rust-src, rustc-dev, llvm-tools-preview and miri components, installs aquascope_front from git at tag v0.3.7, then runs cargo +nightly-2024-12-15 miri setup. You then enable the preprocessor with a [preprocessor.aquascope] section in book.toml.

### Is Aquascope worth adopting for a Rust course?

It is worth it if your material is an mdBook and your readers struggle to predict borrow-checker rejections from prose alone. It is a poor fit if you need a stable toolchain or a visualizer that works outside an mdBook, since the README requires a specific nightly and the miri setup step.

## Sources

- [cognitive-engineering-lab/aquascope on GitHub](https://github.com/cognitive-engineering-lab/aquascope)
- [License: MIT](https://github.com/cognitive-engineering-lab/aquascope/blob/main/LICENSE)
- [Project website](https://cel.cs.brown.edu/aquascope/)
- [README](https://github.com/cognitive-engineering-lab/aquascope/blob/main/README.md)
- [Releases](https://github.com/cognitive-engineering-lab/aquascope/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cognitive-engineering-lab-aquascope