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)