Jupyter Book is an open-source tool that builds publication-quality books, documentation, and websites from Jupyter notebooks and MyST Markdown. It runs your code, captures the output, and turns the whole thing into an HTML site or a PDF. Researchers, data scientists, and educators reach for it when the content is computational: the numbers, plots, and tables on the page come from code that actually executed.
This Jupyter Book review covers what the tool is, who it fits, how the MyST engine works, and where it falls short. If you're comparing documentation stacks more broadly, it sits near Sphinx documentation, Read the Docs, and Material for MkDocs in the technical-publishing space, and it pairs naturally with a docs-as-code workflow. Its closest head-to-head rival is Quarto, which we compare in detail below.
What is Jupyter Book?
Jupyter Book is part of the Jupyter ecosystem, developed under the Executable Books umbrella. The pitch is simple: write content as notebooks or Markdown, and get a structured, cross-referenced book out the other end. It handles multi-page navigation, numbered figures and equations, citations from a BibTeX file, and export to both web and print formats.
The tool grew out of academic and scientific publishing. A researcher writing a computational methods paper, a professor building an interactive textbook, or a data team documenting an analysis pipeline all share the same need: prose and live code in one document, rendered cleanly. Jupyter Book was built for exactly that shape of content, which is why it feels different from a general-purpose docs generator.
Who is it for?
The core audience is technical and academic. Data scientists use it to publish reproducible analyses. Instructors build course materials where students can read the explanation and run the code alongside it. Research groups turn notebook collections into browsable books with proper citations. Open-source scientific libraries document their APIs next to worked examples.
It's a poor fit for teams that don't work in notebooks. If you're a SaaS founder writing product help articles, a general docs site is a better match than a computational book engine. Jupyter Book earns its keep when code execution and academic formatting matter. When they don't, its strengths become overhead you pay for but never use.
Jupyter Book vs Quarto vs a general docs SSG
Here's how Jupyter Book lines up against Quarto and a typical static site generator like MkDocs. The three tools overlap but optimize for different jobs.
| Factor | Jupyter Book | Quarto | General docs SSG (MkDocs) |
|---|---|---|---|
| Primary input | Notebooks + MyST Markdown | .qmd files, notebooks, R Markdown | Plain Markdown |
| Executable code | Yes, native (Python, more via kernels) | Yes, native (Python, R, Julia) | No, code shown as static text |
| Outputs | HTML site, PDF | HTML, PDF, Word, slides, more | HTML site |
| Best for | Notebook-driven books, research docs | Multi-language scientific publishing | Product and software docs |
| Learning curve | Moderate (MyST + config) | Moderate (own CLI + syntax) | Low (Markdown + one YAML file) |
The pattern is clear. Jupyter Book and Quarto both run code and produce print-ready output, which general SSGs don't attempt. Quarto casts a wider net across languages and output formats. A general SSG stays simpler and faster to learn but treats code as text. Pick based on whether execution and academic formatting are part of the job.
How Jupyter Book works
The current release, Jupyter Book 2, is built on the MyST Document Engine. This is a meaningful architecture change from Jupyter Book 1, which was built on Sphinx, the long-standing Python documentation system. The move to MyST brings faster builds and a more modern toolchain, though the version 1 line and its Sphinx foundation still exist for projects that depend on it.
MyST Markdown and notebooks
Content comes from two sources. The first is Jupyter notebooks (.ipynb), the familiar mix of code cells and output. The second is MyST Markdown, an extended flavor of Markdown that adds the structured features plain Markdown lacks: directives, roles, admonitions, figures with captions, and cross-reference targets. You can write an entire book in MyST files, in notebooks, or mix both freely.
MyST (Markedly Structured Text) is what gives Jupyter Book its academic muscle. A plain Markdown file can't number your equations or link "see Figure 3" to the actual figure. MyST syntax can. It reads like Markdown for the simple parts and reaches for directive blocks when you need a labeled theorem, a margin note, or a grid of cards.
Executable content
The defining feature is executable code. When Jupyter Book builds, it can run the code cells in your notebooks and MyST files, then embed the fresh output in the page. A plot regenerates from the data. A table reflects the current computation. This is what makes the output reproducible: readers see results that the build actually produced, not screenshots pasted in by hand.
Cross-references and citations
Academic writing lives on references, and Jupyter Book handles them well. You can label any figure, equation, table, section, or code block, then reference it from anywhere in the book with automatic numbering. Citations pull from a standard BibTeX file and render a formatted bibliography. For anyone who has fought a word processor over figure numbering, this alone can justify the switch.
Output formats
Jupyter Book targets two main outputs. The first is a static HTML website: multi-page, searchable, with a navigation sidebar, dark mode, and a clean reading layout. This is what most people deploy, often to GitHub Pages, Netlify, or a similar host, since the build is just static files.
The second is PDF, for readers who want a printed book or a document to submit. Getting a polished PDF usually involves a LaTeX toolchain, which adds setup on your machine but produces genuinely print-quality typography. The single-source model matters here: one set of notebooks and MyST files feeds both the website and the PDF, so you don't maintain two copies.
Key features
A quick rundown of what you get out of the box:
- Executable code cells that run at build time and embed live output
- MyST Markdown for structured, cross-referenced technical content
- Numbered figures, equations, and tables with automatic reference links
- BibTeX citations and formatted bibliographies
- HTML and PDF output from a single source
- Multi-page book structure defined in a table-of-contents file
- Notebook integration so existing
.ipynbfiles drop straight in - Interactive elements like launch buttons that open notebooks in Binder or Colab
That last feature is a favorite in education. A reader can hit a button and open the live notebook in a hosted environment, no local install required. For teaching computational methods, that removes the biggest barrier to getting students running code.
Setup overview
Getting started is a Python install. You add the package with pip, create a table-of-contents file that lists your chapters, drop in your notebooks and MyST files, then run a build command that produces the HTML site. Deploying is copying the output folder to any static host.
The learning curve is moderate. The install and first build are quick. What takes time is learning MyST directive syntax and configuring the book: the table of contents, citation settings, execution options, and theme tweaks. It's more involved than a plain Markdown site but far less than a hand-rolled Sphinx or LaTeX project. Budget an afternoon to get comfortable.
Pros
Where Jupyter Book earns its reputation:
- Reproducible by design. Output comes from code that ran during the build, so results stay honest.
- First-class notebook support. If your work already lives in notebooks, publishing is a short step rather than a rewrite.
- Real academic formatting. Cross-references, numbered equations, and citations work the way a research document needs them to.
- Single source, two formats. One project produces both a website and a PDF.
- Open source and free. No license cost, no per-seat pricing, MIT-licensed.
- Modern engine. Jupyter Book 2 on MyST builds faster than the older Sphinx-based line.
Cons and limitations
The honest tradeoffs:
- Opinionated toward science and academia. The defaults, features, and docs all assume computational or scholarly content. General product docs feel like a stretch.
- MyST has a learning curve. The syntax is powerful but is one more thing to learn beyond plain Markdown.
- PDF export needs LaTeX. Print-quality output means installing and occasionally debugging a LaTeX toolchain.
- Version transition. Jupyter Book 2 is newer and still maturing; some version 1 features and workflows are still being ported, so check parity for anything you depend on.
- Not a hosted platform. You build static files and host them yourself. There's no managed dashboard, no built-in analytics, no one-click publish.
- Narrow lane. It does computational books well and everything else at a disadvantage compared with purpose-built tools.
Who should use Jupyter Book
Use it if your content is genuinely computational and you want it published cleanly. Strong fits include:
- Data scientists publishing reproducible analyses or reports
- Researchers turning notebook collections into cited, browsable books
- Educators building interactive textbooks and course materials
- Scientific open-source projects documenting methods alongside runnable examples
If any of those describe you, Jupyter Book is close to purpose-built for the job, and free.
Who should not use it
Skip it if your content isn't notebook-driven. A marketing team, a support team, or a SaaS company writing user-facing product docs will fight the tool's academic bias the whole way. You'd spend effort learning MyST and configuring execution features you never use, then still have to host and maintain the site yourself.
For product documentation, the priorities are different: branded design, fast publishing, a live editor, and hosting that just works. That's a different category of tool. Teams who want product or user docs generated from their existing site and hosted with SSL usually reach for a managed platform instead of a computational book engine. Docsio sits in that lane: paste your product URL, get a branded docs site generated in minutes, edit it with an AI agent in a live preview, and publish with one click. It won't run your notebooks, and it isn't trying to. For a research book, use Jupyter Book. For a SaaS docs site, an AI docs generator solves the problem you actually have.
Best alternatives
If Jupyter Book isn't quite right, two directions are worth a look.
Quarto is the closest alternative for computational publishing. It runs code across Python, R, and Julia, and exports to HTML, PDF, Word, and slide decks from one source. If your team works beyond Python or you need presentation output, Quarto often wins. The two tools solve similar problems with different bets on scope.
General documentation tools cover everything else. For software and API docs, a static site generator or a managed platform fits better than a book engine. Our roundup of documentation tools surveys the field, and for product docs specifically, an AI docs generator removes the writing and hosting work that Jupyter Book leaves on your plate.
The verdict
Jupyter Book is an excellent tool inside its lane and an awkward one outside it. For notebook-driven, computational, or academic content, it turns a pile of notebooks into a polished, reproducible, cited book with both web and print output, all for free. The move to the MyST engine in Jupyter Book 2 keeps it current and fast. That's a strong package for the audience it targets.
The catch is that the lane is narrow. If your documentation isn't computational, the academic bias and self-hosted model become friction rather than features. Match the tool to the content. Researchers and educators should try it. SaaS teams writing product docs should look at a managed docs platform first.
Frequently asked questions
What is Jupyter Book used for?
Jupyter Book builds publication-quality books, documentation, and websites from Jupyter notebooks and MyST Markdown. It runs code cells at build time and embeds live output, so it's used mainly for reproducible research reports, computational textbooks, data science analyses, and scientific documentation that mixes prose with runnable code.
Is Jupyter Book free?
Yes. Jupyter Book is fully free and open source, released under the MIT license as part of the Jupyter and Executable Books ecosystem. There's no paid tier, no per-seat cost, and no license fee. You build static output and host it wherever you like, including free options like GitHub Pages.
What is the difference between Jupyter Book and Quarto?
Both run code and produce HTML and PDF, but Quarto casts a wider net. It supports Python, R, and Julia natively and exports to more formats, including Word and slides. Jupyter Book centers on the Jupyter and MyST ecosystem. Pick Quarto for multi-language or presentation needs, Jupyter Book for notebook-first workflows.
Does Jupyter Book use Sphinx?
Jupyter Book 1 was built on Sphinx, the Python documentation system. The current Jupyter Book 2 is built on the MyST Document Engine instead, which brings faster builds and a modern toolchain. The version 1 line and its Sphinx foundation still exist for projects that depend on it, but new work targets the MyST engine.