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 about 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 and installation

Note

You may also use a short-hand for jupyter-book in the command-line interface: jb. 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 simple Jupyter Book that you can customize.

jupyter-book create [OPTIONS] PATH_BOOK

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