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

-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