The Rust Performance Book: what nnethercote/perf-book covers and how to build it locally

What the Rust Performance Book actually is

This repository is the source of a book, not a crate. There is no Cargo.toml at the top level, and the top-level entries are .editorconfig, .github/, .gitignore, CODE_OF_CONDUCT.md, CONTRIBUTING.md, LICENSE-APACHE, LICENSE-MIT, README.md, book.toml and src/. The README points readers at the rendered HTML book hosted at nnethercote.github.io/perf-book, which is the intended reading experience. The problem it solves is narrow and real: Rust gives you control over allocation, monomorphization and memory layout, and that control is easy to spend badly. A compiler-agnostic guide that explains where time goes in Rust programs, and which knobs exist, is useful precisely because the language does not hide those decisions from you.

The audience is Rust programmers who already have working code and want it faster. If you are still learning ownership or traits, the chapters will read as a list of techniques without context. The book is also opinionated about process: the README says suggestions are welcome but prefers them filed as issues rather than pull requests, because the author rewrites contributed ideas in his own words. It also states that the book contains no material produced by generative AI and that none will be accepted. That is a maintenance policy, and it shapes how you should expect to contribute.

How the book is put together with mdBook

The build system is mdBook, the same static site generator used by the official Rust book. The repository layout is the standard mdBook shape: book.toml holds the configuration, and src/ holds the chapter sources. Running the build produces a book/ directory of static HTML, CSS and JavaScript that you can open from the filesystem or serve from any static host. There is no server component, no database and no runtime dependency beyond the generated files.

The data flow is one-directional. Markdown files in src/ are the source of truth; book.toml names the book and configures how mdBook renders it; mdbook build reads both and writes book/. The README also documents mdbook test, which runs the code blocks embedded in the book. That matters for a performance text, because examples that no longer compile are worse than no examples. The README notes the ePub output is currently disabled in the build, with a link to a failed GitHub Actions run, and explains that the ePub file was generated with mdbook-epub, described there as experimental, with excessive whitespace and a worse reading experience than HTML. So the HTML book is the supported artifact and the ePub path is parked.

Building and reading the book locally

The README gives the install step directly: mdBook is installed from crates.io with cargo. If you already have a Rust toolchain, this is the only dependency you need to add.

cargo install mdbook

With mdbook on your PATH, build the book from the repository root. The generated files land in book/, and you should see mdBook report the chapters it rendered.

mdbook build

For reading while you work, the README recommends the development server. It launches a local web server on port 3000, so you open localhost:3000 in a browser. While it runs, the rendered book updates automatically when the book's files change, which makes it practical to keep open beside an editor.

mdbook serve

If you intend to modify or verify examples, the README also documents the test command. It exercises the code within the book rather than the book's prose.

mdbook test

That is the whole workflow. There is no separate install of the book itself; you either read the hosted HTML or build it from source.

Where the book stops being the right tool

The most important limitation is that this is a book. It does not profile your program, it does not ship a crate you can depend on, and it does not provide a measurement harness. If you want a tool that attributes time to functions in a running binary, you need a profiler, and the book's role is to explain concepts and point at techniques rather than to produce numbers for you.

A second constraint is the contribution model. The README is explicit that pull requests are not the preferred channel; the author takes the underlying idea and rewrites it. For a reader who just wants to fix a typo, that is friction by design. Combined with the stated policy on generative AI material, this is a deliberately curated document with a single editorial voice, not a wiki. If your team wants to maintain a shared internal performance handbook with many contributors, this repository is a poor base for that, because the maintainer's stated preference works against broad co-editing.

The third gap is versioning. The repository carries no releases, and the README does not document a versioning scheme or a changelog. The book tracks the language as the author updates it; there is no tagged edition you can pin to a toolchain. If you need guidance tied to a specific Rust release, verify the chapter content against that release yourself.

Maintenance is worth stating plainly: the last push was on 2026-04-23. The repository is not archived, and the README's contribution rules describe an active editorial process, but the cadence is the author's, not a release train.

Alternatives and how their approach differs

The search terms around this project mix it up with Denis Bakhvalov's Performance Analysis and Tuning on Modern CPUs, and the confusion is understandable because both are performance books. The difference in approach is the target. This repository is about Rust specifically: language-level decisions such as allocation patterns, trait dispatch and data layout, plus the profiling workflow around them. Bakhvalov's book is about CPU-level performance analysis across languages, covering microarchitecture, profiling methodology and tuning on modern processors. If your bottleneck is cache behavior or instruction-level effects and you are working in C, C++ or Rust, the CPU-focused book addresses that layer. If your bottleneck is Rust code structure, this book is the closer match.

Perf-ninja, which also appears in the related searches, is a different kind of resource again: a set of exercises rather than a linear text. If you learn by doing measured tasks with a grader, that format fits better than reading chapters. The Rust Performance Book has no exercises and no scoring; its value is in the prose and the examples embedded in the markdown.

Within Rust itself, the obvious companion is the standard library and compiler documentation, which the book cites rather than replaces. The book is not a substitute for reading the docs of the crates you use; it is a layer above them, telling you which questions to ask about the code you already have.

Licence and what that means for reuse

The README states the work is licensed under either the Apache License, Version 2.0 or the MIT license, at your option, with LICENSE-APACHE and LICENSE-MIT in the repository root. That dual arrangement is the common Rust ecosystem pattern and is permissive: you can reuse and adapt the text under either licence. The README also states that, unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work is dual licensed under the same terms without additional conditions.

Two practical notes follow from that, and neither is legal advice. First, if you republish or adapt chapters, you need to comply with whichever licence you pick, which includes attribution and notice requirements. Second, because contributions arrive under the same dual licence, quoting the book in internal documentation is straightforward, but check your own organization's rules before redistributing it externally. The repository does not document a trademark policy or a preferred citation format, so if you need one, that is a question for the maintainer through the issue tracker.

What to check before you commit to it

Start with the hosted HTML at nnethercote.github.io/perf-book and read the table of contents rather than a single chapter. That tells you in a few minutes whether the topics match your current problem, which is faster than cloning and building. If the contents look right, then build locally and run mdbook serve on port 3000 so you have the book beside your editor while you work.

If you find an error, file an issue rather than a pull request. The README is unambiguous about that preference, and a pull request that gets rewritten anyway wastes your time. Because the repository carries no releases, treat the master branch as the current state of the book and re-check it when you upgrade your toolchain, since the guidance can shift with compiler behavior.

Editorial conclusion

Adopt it if you write Rust and want a single reference for profiling, allocation and optimization techniques that you can read offline or build yourself. Do not adopt it if you need runnable tooling, a benchmark harness, or per-crate API docs; the repository contains book sources under src/ and no library code. Before relying on it, check the rendered book at nnethercote.github.io/perf-book, confirm the chapter set matches your Rust edition and toolchain, and read CONTRIBUTING.md and the Improvements section of the README, which state that suggestions are preferred as issues rather than pull requests and that no generative AI material is accepted.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. nnethercote/perf-book on GitHub
4. README