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 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