Jupyter Book

2.1.4 · active · verified Thu Apr 16

Jupyter Book is an open-source tool for building publication-quality books and documents from computational material. It enables users to write content using Markdown or Jupyter notebooks, embed computational elements, and generate interactive web-based books and publication-quality PDFs. Currently at version 2.1.4, it is an actively developed sub-project of Project Jupyter, with its evolution guided by the Executable Books Project community.

Common errors

```
jupyter: command not found
```
cause The `jupyter-book` executable is not in your system's PATH, or Jupyter Book was not installed correctly.

fix Ensure `pip install jupyter-book` completed successfully. Verify your Python environment's script directory is in your system's PATH. If using a virtual environment, ensure it's activated. Reinstalling Python/Anaconda with default settings can often fix PATH issues.
```
WARNING: 'jupyter_execute_notebooks' is deprecated for 'nb_execution_mode' [mystnb.config]
```
cause You are using an old configuration option name in your `myst.yml` or `_config.yml` file.

fix Update your configuration file(s). Replace `jupyter_execute_notebooks` with `nb_execution_mode`. Check other deprecated options in the `myst-nb` documentation.
```
Syntax errors related to MyST/Sphinx directives, e.g., 'Unknown directive type 'my-directive'.'
```
cause The MyST syntax (especially for directives and roles) can be particular and differs from standard Markdown or reStructuredText/Sphinx.

fix Consult the MyST Cheat Sheet and MyST Guide for correct syntax, especially for directives, cross-references, and admonitions. Ensure custom Sphinx extensions are correctly configured for MyST.
```
FileNotFoundError: [Errno 2] No such file or directory: 'pdflatex'
```
cause When building a PDF with the `pdflatex` builder, the `pdflatex` command (part of a LaTeX distribution) is not found in your system's PATH.

fix Install a full LaTeX distribution (e.g., TeX Live, MiKTeX) on your system. Ensure the `pdflatex` executable is accessible from your system's PATH. This is especially common on Windows if a LaTeX distribution is not fully set up.

Warnings

breaking Jupyter Book v2 is a complete rewrite of v1, built on the MyST Document Engine instead of Sphinx. This introduced significant breaking changes.
Fix: Review the official 'Upgrading to Jupyter Book 2' guide. Key changes include web page path conventions (underscores to hyphens), configuration file format (v1: `_config.yml`, v2: `myst.yml`), and some features still being reimplemented or having different behavior.
breaking Updates in `jupyter-book>=0.14` (which incorporates `myst-nb` and `myst-parser` updates) introduced breaking changes, particularly in configuration option names for notebook execution.
Fix: Commonly, `jupyter_execute_notebooks` has been deprecated in favor of `nb_execution_mode`. Refer to the `myst-nb` and `myst-parser` documentation for a complete list of updated configuration options. Warnings are usually issued during build with the new name.
gotcha When using cell tags to hide inputs or outputs, the content may briefly appear before the JavaScript fully loads and hides it.
Fix: This is a minor visual artifact due to client-side rendering. There is no direct fix, but optimizing page load times can reduce its visibility.
gotcha Jupyter Book is primarily a command-line interface (CLI) tool. It is not typically imported as a Python library for programmatic use in user code, but rather orchestrates other Python packages like Sphinx, MyST-NB, and MyST-Parser.
Fix: Interact with Jupyter Book via its CLI commands (`jupyter book init`, `jupyter book build`, `jupyter book start`) rather than attempting to `import jupyter_book` in Python scripts for core functionality.

Install

pip install jupyter-book Install stable version

Quickstart

This quickstart guides you through setting up a new Jupyter Book project, cloning an example, building it, and serving it locally. The `--execute` flag ensures notebooks are run during the build process.

# 1. Install Jupyter Book
pip install jupyter-book

# 2. Clone a sample project (e.g., mystmd-quickstart)
git clone https://github.com/jupyter-book/mystmd-quickstart.git
cd mystmd-quickstart

# 3. Initialize a Jupyter Book project (creates myst.yml)
jupyter book init .

# 4. (Optional) Install dependencies for notebook execution
pip install -r requirements.txt

# 5. Build your book
jupyter book build . --execute

# 6. Serve your book locally
jupyter book start

view raw JSON →