--- interact_link: content/features/executing.ipynb kernel_name: python3 has_widgets: false title: |- Running each page when building your book prev_page: url: /features/interact.html title: |- Connecting content with JupyterHub and Binder next_page: url: /features/interactive_cells.html title: |- BETA - Adding interactivity to your book pages comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" ---

Executing notebooks

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.

Default execution behavior

By default, Jupyter Book will decide whether to execute your book's content based on the types of files used to store your content. By default, any Jupyter Notebooks will not be executed, Jupyter Book assumes that the notebook outputs are already present in the ipynb file (see below for how to change this behavior). In addition, raw markdown files will also not be executed, as Jupyter Book assumes that any code blocks were meant for viewing only, not running. However, any Jupytext documents content will be executed when the page's HTML is built. This can be either .py, .md, or .Rmd files that have jupytext YAML front-matter.

There are a few ways to alter this behavior, which we'll cover below:

It's possible to execute your book content at build time. There are a few convenience functions and options for this:

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, you may use the --execute flag when you build each page's HTML. 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 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. However, after this, only the pages that have been updated will be executed and converted to HTML, so while this will take a long time the first time you run it (since all your book content will need to run), it should be incrementally faster in subsequent builds.

Here's a quick summary of this behavior:

Type Default --execute
Jupyter Notebooks (.ipynb) Doesn't execute Executes
Raw markdown (.md) Doesn't execute Executes
Jupytext pages (.md, .Rmd, .py) Executes Executes

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

Jupyter Book also provides a convenience command-line function that executes a single Jupyter Notebook and stores the outputs in the same ipynb file.

This is a command-line function that allows you to quickly execute pages of your book and store the content in-line. You can use it with a path to a single book page like so:

jupyter-book run path/to/notebook.ipynb

And it will simply run the execute 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.