Rust Design Patterns: An Open-Source Book of Idioms and Anti-Patterns

What This Repository Is and Who It Serves

The rust-unofficial/patterns repository is an mdbook: a collection of Markdown files compiled into a static website documenting design patterns, anti-patterns, and idioms in the Rust programming language. The README describes it as "an open source book about design patterns and idioms in the Rust programming language" available to read at rust-unofficial.github.io/patterns or download as a PDF.

The audience is a Rust developer who has moved past beginner material and wants to understand not just what compiles, but what is considered good practice in the language. Rust's ownership model, trait system, and type inference create patterns that do not appear in C++ or Java books. A developer familiar with general software design patterns but new to Rust will find material here that is not covered by the official Rust Book, which focuses on language mechanics rather than design guidance.

The book is community-maintained under the rust-unofficial GitHub organization, which exists alongside but separate from the official Rust project. This means the content reflects community consensus rather than any official standard.

Repository Layout and How to Navigate It

The top-level directory contains the mdbook configuration in book.toml, the source content in src/, translation support in po/, styles in styles/, and a template.md used when contributing new patterns. The src/ directory is where the actual pattern documentation lives, organized into design patterns, idioms, and anti-patterns.

The book is browsable online at rust-unofficial.github.io/patterns. For readers who want to work offline, the repository offers a PDF download directly from the hosted URL. Both the HTML site and the PDF are generated from the same Markdown source.

The contributing guide and the umbrella issue at github.com/rust-unofficial/patterns/issues/116 track which patterns, anti-patterns, and idioms still need documentation. Checking that issue gives a realistic picture of the book's current coverage. Not every pattern that exists in Rust codebases has a corresponding entry; the book is a living document with known gaps.

Building the Book Locally with mdbook

The book is built with mdbook, a Rust tool for compiling Markdown into static HTML. Install it with:

cargo install mdbook

Three additional tools are needed for the full feature set. The README lists them:

cargo install mdbook-last-changed
cargo install mdbook-pandoc
cargo install mdbook-i18n-helpers

The `mdbook-last-changed` plugin adds last-changed dates to the footer of each page. The `mdbook-pandoc` plugin generates the PDF output. The `mdbook-i18n-helpers` plugin supports the translation workflow using the po/ directory.

PDF generation also requires Texlive and Pandoc. The README gives the commands for a Debian-based system:

sudo apt-get update
sudo apt-get install -y texlive texlive-latex-extra texlive-luatex texlive-lang-cjk librsvg2-bin fonts-noto

Once the dependencies are installed, two commands cover the main use cases. To build the static HTML output into the /book directory:

mdbook build

To serve the book locally with live reload on file changes:

mdbook serve

The serve command starts a local server at http://localhost:3000 by default. The README notes that the port is changeable and to check the terminal output to confirm the actual address. For most readers, browsing the hosted version is simpler than building locally; the local build is most useful when contributing new content or previewing edits before submitting a pull request.

What the Book Covers: Patterns, Idioms, and Anti-Patterns

The book is organized into three categories. Design patterns are recurring, proven solutions to problems that arise in Rust codebases, adapted from the broader software design pattern literature but accounting for Rust's ownership and lifetime constraints. Idioms are lower-level, Rust-specific conventions around style and usage that experienced Rust developers consider standard. Anti-patterns document approaches that look reasonable but create problems in Rust specifically, usually around ownership, lifetime management, or the type system.

This three-part structure is more useful than a simple pattern list because Rust has a significant body of anti-patterns that come from developers applying habits from garbage-collected languages. A pattern that works well in Python or Java may fight the borrow checker in Rust. The anti-pattern section names these explicitly.

The umbrella issue tracks the backlog of patterns still to be documented. This is a direct indicator of coverage: the book does not claim to be comprehensive, and the maintainers acknowledge there is more to add. A reader who looks for a specific pattern and does not find it should check the issue before assuming the pattern is not relevant to Rust.

Limitations: Coverage Gaps and Community Maintenance Model

The most significant practical limitation of this resource is incomplete coverage. The umbrella issue at github.com/rust-unofficial/patterns/issues/116 explicitly lists patterns, idioms, and anti-patterns that are identified but not yet written. For a team that wants to use the book as a complete style reference, those gaps require either tolerating them or contributing the missing entries.

The book is community-maintained, which means there is no organization or company funding review time or ensuring consistency across entries. An entry may reflect the practices of one contributor rather than community consensus. Some entries have more rigorous analysis than others.

Because Rust itself continues to evolve, some patterns documented in the book may become outdated as language features change. The mdbook-last-changed plugin adds dates to entries, which helps identify content that has not been touched recently, but it does not guarantee that older entries remain accurate for the current edition of Rust.

The repository's last push was on 2026-09-21. It is licensed under MPL-2.0, which means adaptations and modifications must be shared under the same license, but the book can be incorporated into larger documentation sets that use different licenses for their own content as long as the covered files remain under MPL-2.0.

Rust Design Patterns vs the Official Rust Book

The official Rust Book (doc.rust-lang.org/book) is the natural comparison point. The official book covers the language from first principles: ownership, borrowing, lifetimes, traits, generics, and the standard library. It is comprehensive on language mechanics and has a thorough chapter structure aimed at new Rust developers.

What the official book does not cover is design patterns: recurring architectures for organizing Rust programs, advice on what to avoid when writing idiomatic code, or examples of how the ownership model leads to different structural choices than a language with a garbage collector would. This is the gap that rust-unofficial/patterns fills.

The two resources are complementary. A developer learning Rust should start with the official book to understand the language, and then use rust-unofficial/patterns to understand how practitioners apply it. Neither replaces the other.

Contributing and License

The README invites contributions and points to the CONTRIBUTING.md and the umbrella issue for guidance on what is needed. The template.md file provides a starting structure for new pattern entries, which helps new contributors match the format of existing entries.

The license is MPL-2.0 (Mozilla Public License 2.0). This is a file-level copyleft license: modifications to covered source files must be released under the MPL-2.0, but combining the book with other content under a different license is permitted as long as the covered files themselves remain under MPL-2.0. This is a meaningful difference from the GPL, which extends copyleft to the larger work.

Editorial conclusion

rust-unofficial/patterns is the right resource for a Rust developer who has learned the language basics and wants to understand how experienced practitioners structure code for safety, clarity, and idiomatic ownership use. It is not a substitute for the official Rust Book, which covers fundamentals, and it is not a finished reference: the umbrella issue at github.com/rust-unofficial/patterns/issues/116 shows many patterns still awaiting documentation. Before relying on it for a team onboarding guide, verify that the patterns most relevant to your codebase are covered and up to date. The MPL-2.0 license allows incorporating the text into other documentation under the same license.

Frequently asked questions

Official sources

1. Issues
2. License: MPL-2.0
3. Project website
4. README
5. rust-unofficial/patterns on GitHub