The command-line interface¶

Jupyter Book comes with a command-line interface that makes it easy to build your books and run a few common functions. This page contains information on what you can do with the CLI.

This page is a complete reference for the CLI. For newcomers who would like to get started with the Jupyter Book CLI, we recommend starting with Overview

Note

You may also use jb as shorthand for jupyter-book in the command-line. For example: jupyter-book build mybook/ is equivalent to jb build mybook/.

See below for the full command-line reference

jupyter-book¶

Build and manage books with Jupyter.

jupyter-book [OPTIONS] COMMAND [ARGS]...

Options

--version¶: Show the version and exit.

build¶

Convert your book’s or page’s content to HTML or a PDF.

jupyter-book build [OPTIONS] PATH_SOURCE

Options

--path-output <path_output>¶: Path to the output artifacts

--config <config>¶: Path to the YAML configuration file (default: PATH_SOURCE/_config.yml)

--toc <toc>¶: Path to the Table of Contents YAML file (default: PATH_SOURCE/_toc.yml)

-W, --warningiserror¶: Error on warnings.

-n, --nitpick¶: Run in nit-picky mode, to generates warnings for all missing references.

--keep-going¶: With -W, do not stop the build on the first warning, instead error on build completion

--all¶: Re-build all pages. The default is to only re-build pages that are new/changed since the last run.

--builder <builder>¶

Which builder to use.

Options: html|pdfhtml|latex|pdflatex

-v, --verbose¶: increase verbosity (can be repeated)

-q, --quiet¶: -q means no sphinx status, -qq also turns off warnings

Arguments

PATH_SOURCE¶: Required argument

clean¶

Empty the _build directory except jupyter_cache. If the all option has been flagged, it will remove the entire _build. If html/latex option is flagged, it will remove the html/latex subdirectories.

jupyter-book clean [OPTIONS] PATH_BOOK

Options

-a, --all¶: Remove build directory.

--html¶: Remove html directory.

--latex¶: Remove latex directory.

Arguments

PATH_BOOK¶: Required argument

config¶

Inspect your _config.yml file.

jupyter-book config [OPTIONS] COMMAND [ARGS]...

sphinx¶

Generate a Sphinx conf.py representation of the build configuration.

jupyter-book config sphinx [OPTIONS] PATH_SOURCE

Options

--config <config>¶: Path to the YAML configuration file (default: PATH_SOURCE/_config.yml)

--toc <toc>¶: Path to the Table of Contents YAML file (default: PATH_SOURCE/_toc.yml)

Arguments

PATH_SOURCE¶: Required argument

create¶

Create a Jupyter Book template that you can customize.

jupyter-book create [OPTIONS] PATH_BOOK

Options

--cookiecutter¶: Use cookiecutter to interactively create a Jupyter Book template.

Arguments

PATH_BOOK¶: Required argument

myst¶

Manipulate MyST markdown files.

jupyter-book myst [OPTIONS] COMMAND [ARGS]...

init¶

Add Jupytext metadata for your markdown file(s), with optional Kernel name.

jupyter-book myst init [OPTIONS] [PATH]...

Options

--kernel <kernel>¶: The name of the Jupyter kernel to attach to this markdown file.

Arguments

PATH¶: Optional argument(s)

toc¶

Generate a _toc.yml file for your content folder. It also generates a _toc.yml file for sub-directories. The alpha-numeric name of valid content files will be used to choose the order of pages/sections. If any file is called “index.{extension}”, it will be chosen as the first file. Note that each folder must have at least one content file in it.

jupyter-book toc [OPTIONS] PATH

Options

--filename_split_char <filename_split_char>¶: A character used to split file names for titles

--skip_text <skip_text>¶: If this text is found in any files or folders, they will be skipped.

--output-folder <output_folder>¶: A folder where the TOC will be written. Default is path

--add-titles¶: Whether to generate page titles from file names.

Arguments

PATH¶: Required argument