Command-line interface reference

Command-line interface reference#

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 | dirhtml | singlehtml | pdfhtml | latex | pdflatex | linkcheck | custom

--custom-builder <custom_builder>#

Specify alternative builder provided by Sphinx, including text and epub. This can only be used with –builder=custom. Valid options listed at https://www.sphinx-doc.org/en/master/man/sphinx-build.html

-v, --verbose#

increase verbosity (can be repeated)

-q, --quiet#

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

--individualpages#

[pdflatex] Enable build of PDF files for each individual page

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.

--no-input#

If using cookiecutter, do not prompt the user for input.

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)