interpretable-ml-book: the repository behind a free textbook on black box models

One repository for the text, the R environment and the build

The README is a landing page, not an introduction. It names the project, links to the free online version, the Leanpub ebook and the paperback, and then gets out of the way. Everything else about how the book is made is in the tree.

`manuscript/` is the manuscript directory, which is the signature of a bookdown project: chapters are R Markdown files that get knitted into a book rather than prose that lives in a word processor. Around it sit `cover/` for cover artwork, `data/` for anything the examples load, `scripts/` for helper scripts, `pkg/` for package-related output, and `initialize-gh-pages.sh` as the deployment entry point. `DESCRIPTION` in the root makes the directory an R package skeleton as well, which is how bookdown projects usually keep their metadata in one place.

`renv.lock` is the detail that matters for anyone who wants to run the code rather than read it. renv pins the R package versions the book was written against, so the examples still produce the output shown in the text years later. A book about interpretable machine learning goes stale when a package changes its defaults, and a lock file is the cheapest defence against that.

The build is automated through a GitHub Actions workflow the README badges as `Book.yaml`, so a push to the manuscript produces the site without a manual export step. The deployment script sits at the root of the tree and is what you would run for a local build:

cd interpretable-ml-book
./initialize-gh-pages.sh

Three editions, a new subtitle and an ISBN

The release history is short and tells you the cadence. `v1-print` is dated 2019-04-11 for the first print edition, `v2` on 2022-03-04 for the second, and `v3` on 2025-03-13 for the third. The v2 release note says it covers both ebook and paperback, so the release tags track editions rather than software versions.

The third edition, dated 2025 in the citation, carries the subtitle *A Guide for Making Black Box Models Explainable*. That subtitle is a shift in emphasis worth noticing, because the earlier framing of the project was about interpretable models and this one is explicitly about explaining models that are already black boxes. The README's summary still describes both halves: a first part introducing algorithms that produce simple, interpretable models together with instructions for reading their output, and later chapters focused on analysing complex models and their decisions.

For citation, the README asks for *Interpretable Machine Learning: A Guide for Making Black Box Models Explainable*, third edition, 2025, ISBN 978-3-911578-03-5. It asks this of blog posts and research articles, and asks readers who used the book as a reference to write a line saying what for, which is an unusual invitation from a technical author and one that tells you the intended audience includes people applying this outside research.

The stated audience is broad on purpose: machine learning practitioners, data scientists, statisticians, and stakeholders deciding whether to use machine learning at all.

The R example code depends on a package the author also wrote

The further resources section says most R examples use the `iml` R package, and notes that the author developed it. That single dependency relationship shapes what the book is: it is paired with tooling that Molnar built to make model explanation inspectable from R, so the code in the chapters is code the author could make work rather than pseudocode adapted from documentation.

If you intend to follow along, `iml` is the first thing to install. The second link in that section points to a separate book on SHAP, which suggests where the author's own attention has gone since this one was written, and is a reasonable companion read if your interest is in feature attribution specifically.

What the README does not do is list the R packages each chapter needs. There is no per-chapter dependency list, and `renv.lock` is the only machine readable record of the environment. That is fine for reproducing a single chapter and unhelpful for building an R project on top of the whole book, so plan on picking the parts you need rather than the whole environment.

The examples are R throughout. If your work is in Python, the techniques transfer but the code does not, and the book does not present Python versions of the examples.

Two licence files and a contributor path for fixes

The tree carries both `CC-BY-NC-SA-4.0.txt` and `MIT-License.txt`, which is the first thing to sort out before reusing anything from it. The book text is under a Creative Commons attribution, non-commercial, share-alike licence, and the MIT file appears to cover the code rather than the prose. If you want to quote a chapter in a commercial training programme or a company handbook, the NC clause is the part that gets in the way, and the distinction between text and code is the part to check.

Corrections are welcome and the process is spelled out: fork the repository, create a branch for the fix, address the errors, and open a pull request with a description. Content suggestions and requests go to the issue tracker, with the honest caveat that not every suggestion will be added. Twenty-five open issues against a project of this size suggests the tracker is used for active discussion rather than left to rot.

The README also carries a star history badge, which is the standard way this author tracks interest in the book across editions. It is a reasonable signal that the third edition found an audience, and a poor one for anything else.

Why a book project ships as a public repository at all

There is a reason to write a technical book this way beyond the author's preferences, and it is worth naming for anyone considering the same approach.

Publishing the source means corrections arrive from readers instead of waiting for a print cycle, which for a book whose subject is a fast-moving subfield is the difference between a book that stays usable and one that quietly goes stale. It also means the examples are inspectable, so a reader who disagrees with a piece of code can see exactly what ran. Both of those are things a PDF cannot offer, and both apply to any technical book, not just this one.

The cost is visible in the repository. A `renv.lock` to maintain, an Actions workflow that can break when the bookdown toolchain moves, a separate licence file for code versus text, and a public issue tracker that becomes a permanent obligation rather than a launch week event. Molnar has been doing this since 2019 across three editions, which is the evidence that the maintenance is real rather than aspirational.

The last push was on 2026-07-07, and `CHANGELOG.md` is where the edition-level history lives. The book project is at a stable point rather than mid rewrite, and the third edition remains the current version to read.

Editorial conclusion

This repository is worth reading for a different reason than most: it is a complete publishing pipeline for a technical book, not just a folder of markdown. `manuscript/` holds the text, `renv.lock` pins the R environment the examples run against, `scripts/` and `initialize-gh-pages.sh` build and deploy, and a GitHub Actions workflow named `Book.yaml` does the rest. The book itself is readable for free at the project page, and the third edition carries a new subtitle about making black box models explainable, with an ISBN and a Leanpub edition if you want a copy with a fixed edition number. The `CHANGELOG.md` is where edition-level changes live, and the `iml` package the examples depend on is the piece to install first if you intend to run anything.

Frequently asked questions

Official sources

1. christophM/interpretable-ml-book on GitHub
2. Issues
3. Project website
4. README
5. Releases