Build from the command line

When you’ve written your book’s content, it is now time to build outputs for your book so that you may share them with others. For example, you may wish to build HTML files to host as a static website, or a PDF to share with colleagues.

Build via the command-line

The basic way to build your book is via the following command:

jupyter-book build <path-to-book>

In addition, you may control the kinds of outputs that are generated, and the ways in which your book conducts the build. The rest of the sections on this page cover some of these options.

Types of build outputs

You can build a variety of outputs using Jupyter Book. To choose a different builder, use the --builder <builder-name> configuration when running jupyter-book build from the command-line.

Here is a list of builders that are available to you:

• html: HTML outputs (default)

• singlehtml: A single HTML page for your book

• dirhtml: HTML outputs with <filename>/index.html structure.

• pdfhtml: Build a PDF via HTML outputs (see Build a PDF from your book HTML)

• linkcheck: Run the Sphinx link checker (see Check external links in your book)

• latex: Build Latex files for your book

• pdflatex: Build a PDF of your book via Latex (see Build a PDF using LaTeX)

Clean your book’s generated files

It is possible to “clean up” the files that you generate when you build your book. This is often useful if you have recently changed a lot of content in order to ensure that you build your book from a clean slate.

You can clean up your book’s generated content by running the following command:

jupyter-book clean mybookname/

By default, this will delete all folders inside mybookname/_build except for a folder called .jupyter_cache. This ensures that the content of your book will be regenerated, while the cache that is generated by running your book’s code will not be deleted (because regenerating it may take some time).

To delete the .jupyter_cache folder as well, add the --all flag like so:

jupyter-book clean mybookname/ --all

This will entirely remove the folders in the _build/ directory.

Debug your book’s build process

When debugging your book build, the following options can be helpful:

jupyter-book build -W -n --keep-going mybookname/

This will check for missing references (-n), turning them into errors (-W), but will still attempt to run the full build (--keep-going), so that you can see all errors in one run.

You can also use -v or -vvv to increase verbosity.