The Art of Debugging: a manual for gdb and py-spy with a Prince-based build

Debugging filed by failure kind instead of by language

Two goals open the book: debug normal issues really fast, and make complicated issues possible to debug. The second half is the unusual one. Most debugging help is stored by tool, so you are expected to know you have a segfault before you start reading, and this book is stored by situation instead, across separate chapters on Unix tools, compiled programs, Python and PyTorch. The author frames the hard part precisely, finding the source of a problem being the difficult stage, and holds that once the cause is understood the fix sits close at hand. Everything after that framing exists to shorten the path from symptom to narrowed cause, with a command attached to each step. Readers are people working on C, Python and PyTorch code under Linux or Unix, which is why every topic tag on the repository is a systems one. Nothing here is about web, mobile or data pipelines.

A Python repository whose chapters are C, shell and gdb

GitHub labels the primary language Python, and the topic list adds c, debugging, gdb, linux, segfault and unix. Read the table of contents against that label and the picture changes. Five of the six entries are not Python chapters. Two cover the Unix side with bash, strace, make, prompt and nohup. One covers compiled programs with gdb, ldd, nm, LD_LIBRARY_PATH and LD_PRELOAD. Only the 4th entry is Python work, with py-spy, paths and auto-print, and the 5th is PyTorch: cpu and gpu memory, performance, models and tensors. Python in this repository lives in the build scripts, build/mdbook/md-to-html.py and build/mdbook/preprocess-html-for-epub.py, and that is where the language label comes from. Expect to spend the first two chapters at a terminal watching a C program die rather than reading about Python internals. The sixth entry is not stored here at all, because machine learning project debugging is delegated to the debug folder of the stas00/ml-engineering repository, so the book stops at models and tensors and points elsewhere for the rest.

The hosted PDF can lag behind the master branch

There are two copies of this book and they drift apart. The hosted PDF and EPUB sit on huggingface.co/stas/the-art-of-debugging-book, and the README says the author will try to rebuild them once in a few weeks or so. That sentence is the warning: whatever you download may be older than the Markdown on the master branch, and no page tells you which. If a chapter is missing from the PDF, the answer is the build directory inside the repository, not patience. That directory never appears in the table of contents, which catches out anyone who reads only the front page. The last push was on 2026-09-03 and the project publishes no GitHub releases, so there is no tag to compare the download against. The branch itself is the only reference point you get.

The PDF recipe needs Prince and four pdftk passes

Building the book is not a pip install. The pdf target depends on html, so the Markdown has to be converted before anything is typeset, then a single commercial renderer lays out every chapter in one pass, and 4 pdftk invocations do the assembly afterwards. Each line does a separate job, which is why the recipe is 5 commands long instead of one.

pdf: html ## make pdf version (from html files)
	prince --no-author-style -s build/prince_style.css --pdf-title="Stas Bekman - The Art of Debugging ($$(date))" -o out1.pdf $$(cat chapters-html.txt | tr "\n" " ")
	pdftk out1.pdf dump_data output pdf-bookmarks.txt
	pdftk out1.pdf cat 2-end 1 output out2.pdf
	pdftk images/The-Art-of-Debugging-book-cover.pdf out2.pdf output out3.pdf
	pdftk out3.pdf update_info pdf-bookmarks.txt output "Stas Bekman - The Art of Debugging.pdf"

The first pdftk line extracts bookmark metadata from the finished file. The second, pdftk out1.pdf cat 2-end 1 output out2.pdf, lifts page 1 out of the stream and appends it at the end, moving whatever Prince emitted first to the back where a spine belongs. The third prepends images/The-Art-of-Debugging-book-cover.pdf, and the fourth writes the bookmarks back in and names the result. Prince is the dependency to check first, and no free renderer is wired in as a fallback.

make help hides targets without a trailing comment

The build system is a Makefile whose default goal is help, so a bare make prints usage and stops without building anything. Reading the help recipe is quicker than guessing at target names.

.PHONY: help check-style spell prep-html-files html html-local pdf epub upload fix-tables check-links-local check-links-all check-links-local-fast check-redirects check-programs clean
.DEFAULT_GOAL := help

It filters lines through the pattern /^[a-zA-Z_-]+:.*?##/ and formats whatever survives with awk, which means a target reaches the listing only if its definition ends in a double hash comment. Sixteen targets are named in that .PHONY line, from upload and clean through check-links-local-fast and check-programs, and any of them without that comment stays invisible even though make will still run it when you name it. Expect to read the file yourself when the listing comes up short.

The spell target edits files instead of reporting them

One check in this Makefile modifies your checkout instead of reporting on it. The spell target runs codespell with --write-changes, so every typo found in the prose is repaired on the spot, and the only exclusions are the PDF and JSON files named in the 2 skip flags.

spell: ## spellcheck
	codespell --write-changes --skip "*.pdf" --skip "*.json"

A clean run then tells you nothing about whether anything changed on disk. The lone install hint is a plain comment above the recipe that says to pip install codespell. There is no dry run, no diff preview and no list mode in the target, so the mutation is the default behaviour rather than an opt-in. Running the same tool without --write-changes shows the list first, and that is the safer order to work in when the branch has uncommitted changes.

The chapter order lives in a text file, not a folder

Adding a chapter is not a matter of dropping a Markdown file into a directory. prep-html-files writes book-front.html as the first entry of chapters-html.txt, then a single perl expression rewrites the .md suffix to .html across chapters-md.txt and appends the result.

prep-html-files: ## prepare html-files
	echo book-front.html > chapters-html.txt
	perl -ne 's|\.md|.html|; print' chapters-md.txt >> chapters-html.txt

That text file, not the directory listing, decides the order Prince renders and therefore the order of the printed book, and the pdf target reads the same file back with cat chapters-html.txt. A chapter never added to chapters-md.txt is absent from the built ebook even when the file sits in the correct folder. The repository root shows the same pattern elsewhere, holding both methodology.md and a methodology directory, plus a file called incoming.md that no table of contents entry links to, so anyone hunting for the methodology chapter has two candidates to check.

The SKILL.md file gives agents a second front door

Beyond the 6 chapters, the root holds a SKILL.md that the README describes as a way to teach your AI agent to debug your projects better. It is a second entrance aimed at tools that read instructions before a person does, and it ships alongside companion skills for Machine Learning Engineering and Stas' Python Cookbook, two more open books by the same author. What the front page does not give you is a format, a version, or a list of which chapters the file covers, so you cannot tell whether it tracks the latest text. The text is licensed under Attribution-ShareAlike 4.0 International, so a chapter you copy into internal documentation carries the same terms onward. The alternative route to the same ground is the author's separate cheatsheet repositories, filed one tool at a time in bash-tools, conda-tools, git-tools, jupyter-notebook-tools, make-tools, python-tools, tensorboard-tools and unix-tools. That is a different organising principle from a debugging book filed by failure kind, and those repositories have no home for the compiled-program or PyTorch chapters.

Editorial conclusion

Adopt the-art-of-debugging if you want one searchable home for gdb, strace, py-spy and PyTorch memory problems, and if you can accept prose that says outright that some sections are still a work in progress. Pass on it if you need a pip installable tool or a pinned artifact, because this repository ships no installable package. The compiled-programs and pytorch chapters are the reason to open it. First check whether the chapter you need is in the hosted PDF or only in the Markdown, then run html-local to build it yourself.

Frequently asked questions

Official sources

1. Issues
2. License: CC-BY-SA-4.0
3. README
4. stas00/the-art-of-debugging on GitHub