Executing pages of your book

✨experimental✨

Sometimes you'd like to execute each page's content before building its HTML - this ensures that the outputs are up-to-date and that they still run. Jupyter Book has the ability to execute any code in your content when you build each page's HTML although by default this is disabled for notebook and simple markdown documents.

Default execution behavior

Jupyter Book will decide whether to execute your book's content based on the types of files used to store your content. By default, Jupyter Book assumes that :

• notebook outputs are already present in an .ipynb file, and consequently any Jupyter Notebooks (.ipynb documents), will not be executed; (see below for how to change this behavior);
• simple raw markdown files (.md, no Jupytext header) will also not be executed: Jupyter Book assumes that any code blocks were meant for viewing only, not running;
• any Jupytext documents (currently, .py, .md, or .Rmd files that have jupytext YAML front-matter content) will be executed when the page's HTML is built.

There are a few ways to alter this behavior in order to execute your book content at build time using several convenience functions and options which we'll cover below.

Run a single page in-place: jupyter-book run

Jupyter Book provides a convenience command-line function that executes one or more Jupyter Notebooks and stores the outputs inline within the same ipynb file. This provides a straightforward way of ensuring that source notebook files contain freshly computed cell outputs when you create your Jupyter Book.

This jupyter-book run command-line function can be called with the path to a single book page like so:

jupyter-book run path/to/notebook.ipynb

It will simply execute the notebook and insert the code cell outputs in-place.

You can also specify a folder with a collection of pages as the first argument:

jupyter-book run path/to/notebook_folder

In this case, all notebooks in this folder and sub-folders will be run in-place.

Run all your book's content when building: jupyter-book build --execute

If you'd like to run each page of your book (where possible) when building the HTML for your book pages without modifying the original source document, use the --execute flag when building each page's HTML:

jupyter-book build --execute

This will cause each .ipynb and jupytext-formatted page to be executed when it is built. In this case, the source content files will not be modified, but the code execution outputs will be placed in each page's HTML.

Remember that the HTML for each page is cached until you update your content. The first time you run jupyter-book build --execute, each page of your book will be run and converted to HTML which may take some time. However, after the first run, only the pages that have been updated will be executed and converted to HTML, which should lead to subsequently faster build times as you update your content.

Here's a quick summary of this behavior: