How to Export Jupyter Notebooks into Other Formats

When working with Jupyter Notebook, you will find yourself needing to distribute your Notebook as something other than a Notebook file. The most likely reason is that you want to share the content of your Notebook to non-technical users that don’t want to install Python or the other dependencies necessary to use your Notebook. The most popular solution for exporting your Notebook into other formats is the built-in nbconvert tool. You can use nbconvert to export to the following formats:

HTML (–to html)
LaTeX (–to latex)
PDF (–to pdf)
Reveal JS (–to slides)
Markdown (md) (–to markdown)
ReStructured Text (rst) (–to rst)
executable script (–to script)

The nbconvert tool uses Jinja templates to convert your Notebook files (.ipynb) to these other static formats. Jinja is a template engine for Python. The nbconvert tool depends on Pandoc and TeX for some of the conversions that it does. You may need to install these separately on your machine. This is documented on ReadTheDocs.

Want to learn more about working with Jupyter Notebook? Then check out my book:

Jupyter Notebook 101

Purchase now on Leanpub

Using nbconvert

The first thing we need is a Notebook that we want to convert. I did a presentation on Python decorators where I used a Jupyter Notebook. We will use that one. You can get it on Github. If you would like to use something else, feel free to go download your favorite Notebook. I also found this gallery of interesting Notebooks that you could use for too.

The Notebook that we will be using is called Decorators.ipynb. The typical command you use to export using nbconvert is as follows:

jupyter nbconvert  --to

The default output format is HTML. But let’s start out by trying to convert the Decorators Notebook into a PDF:

jupyter nbconvert Decorators.ipynb --to pdf

I won’t mention this for every nbconvert run, but when I ran this command, I got the following output in my terminal:

[NbConvertApp] Converting notebook Decorators.ipynb to pdf
[NbConvertApp] Writing 45119 bytes to notebook.tex
[NbConvertApp] Building PDF
[NbConvertApp] Running xelatex 3 times: [u'xelatex', u'notebook.tex']
[NbConvertApp] Running bibtex 1 time: [u'bibtex', u'notebook']
[NbConvertApp] WARNING | bibtex had problems, most likely because there were no citations
[NbConvertApp] PDF successfully created
[NbConvertApp] Writing 62334 bytes to Decorators.pdf

You will see something similar when you convert your Notebook to other formats, although the output will differ obviously. This is what the output looked like:

If you convert a Notebook to reStructuredText or latex, than nbconvert will use pandoc underneath the covers to do the conversion. That means that pandoc is a dependency that you may need to install before you can do a conversion to one of those formats.

Let’s try converting our Notebook to Markdown just to see what we get:

jupyter nbconvert Decorators.ipynb --to markdown

When you run this command, you will get output that looks like this:

Let’s do one conversion of our Notebook. For this conversion, we will turn our Notebook into HTML. The HTML conversion actually has two modes:

–template full (default)
–template basic

The full version will make the HTML render of the Notebook look very much like a regular Notebook looks when it is in its “interactive view” whereas the basic version uses HTML headers and is mostly aimed at people who want to embed the Notebook in a web page or blog. Let’s give it a try:

jupyter nbconvert Decorators.ipynb --to html

When I ran this, I got a nice single HTML file. If you open the HTML in your web browser, you should see the following:

Converting Multiple Notebooks

The nbconvert utility also supports converting multiple Notebooks at once. If you have a set of Notebooks with similar names, you could use the following command:

jupyter nbconvert notebook*.ipynb --to FORMAT

This would convert all the Notebooks in your folder to the format you specify as long as the Notebook began with “notebook”. You can also just provide a space delimited list of Notebooks to nbconvert:

jupyter nbconvert Decorators.ipynb my_other_notebook.ipynb --to FORMAT

If you have many Notebooks, another method of converting them in bulk is to create a Python script that acts as configuration file. According to this documentation you can create a Python script with the following contents:

c = get_config()
c.NbConvertApp.notebooks = ["notebook1.ipynb", "notebook2.ipynb"]

If you save this, you can then run it using the following command:

jupyter nbconvert --config mycfg.py

This will then convert the listed Notebooks to the format of your choice.

Executing Notebooks

As you might expect, most of the time, Jupyter Notebooks are saved with the output cells cleared. What this means is that when you run the conversion you won’t get the output in your export automatically. To do this feat, you must use the –execute flag. Here is an example:

jupyter nbconvert --execute my_notebook.ipynb --to pdf

Note that the code in your Notebook cannot have any errors or the conversion will fail. This is why I am not using the Decorators Notebook in this example as I have some purposely created cells that fail for demonstration purposes.

Executing Notebooks with Python

You can also create a Python script that you can use to execute your Notebooks programmatically. Let’s write some code that will run all the cells in my Decorators Notebook including the ones that will throw exceptions. Let’s create an empty Python script and name it notebook_runner.py. Enter the following code into your editor:

# notebook_runner.py

import nbformat
import os

from nbconvert.preprocessors import ExecutePreprocessor


def run_notebook(notebook_path):
    nb_name, _ = os.path.splitext(os.path.basename(notebook_path))
    dirname = os.path.dirname(notebook_path)
    
    with open(notebook_path) as f:
        nb = nbformat.read(f, as_version=4)
        
    proc = ExecutePreprocessor(timeout=600, kernel_name='python3')
    proc.allow_errors = True
    
    proc.preprocess(nb, {'metadata': {'path': '/'}})
    output_path = os.path.join(dirname, '{}_all_output.ipynb'.format(nb_name))
    
    with open(output_path, mode='wt') as f:
        nbformat.write(nb, f)
    
if __name__ == '__main__':
    run_notebook('Decorators.ipynb')

The first items of interest are at the top of the code. Here we import nbformat and a preprocessor from nbconvert.preprocessors that is called ExecutePreprocessor. Next we create a function called run_notebook that accepts a path to the Notebook that we want to run. Inside of this function we extract the file name and the directory name from the path that we passed in.

Then we read the Notebook file using nbformat.read. You will note that you can tell nbformat what version to read the file as. Be sure to set this to match whichever version of Jupyter Notebook you are using. The next step is to instantiate the ExecutePreprocessor class. Here we give it a timeout and the kernel name. If you were using something other than Python this is where you would want to specify that information.

Since we want to ignore errors, we set the allow_errors attribute to True. The default is False. If we hadn’t done this, we would need to wrap the next step in a try/except block. Anyway, we then tell Python to do the preprocessing via the preprocess method call. You will note that we need to pass in the Notebook data that we read as well as tell it where the Notebook is located via a dictionary of metadata. Be sure to update this if your path is different than the one used in this example.

Finally we create the output path and write out our the Notebook to a new location. If you open it up, you should see output for all of the code cells that actually produce output.

Configuration

The nbconvert utility has many configuration options that you can use to customize how it works. For full details, I recommend reading the documentation here.

Wrapping Up

In this article we learned how to export / convert our Jupyter Notebooks into other formats such as HTML, Markdown, and PDF. We also learned that we can convert multiple Notebooks at once in several different ways. Finally we learned different ways to execute a Notebook before exporting it.