Jump Out of the Jupyter Notebook with nbconvert | by Jeff Hale | Towards Data Science

If you’re a data scientist, nbconvert is a great tool to add to your tool belt. With nbconvert you can easily turn your Jupyter Notebook into a Python script from the command line. It also allows you to turn your Jupyter notebook into share-friendly formats like .html and.pdf files. How cool is that?
nbconvert is an open source software project that comes bundled with Anaconda. To quote the nbconvert docs, it enables:
presentation of information in familiar formats, such as PDF.
publishing of research using LaTeX and opens the door for embedding notebooks in papers.
collaboration with others who may not use the notebook in their work.
sharing contents with many people via the web using HTML.
This guide is current as of nbconvert version 5.4. Let’s dig in to how to use it!
Although nbconvert comes installed with Anaconda, it can be installed with pip, too. You can convert your Jupyter notebook to some file formats, such as HTML, right out of the box.
However, if you want to covert a notebook to LaTex, PDF, Ascii, reStructuredTExt, or Markdown, you’ll need to install Pandoc and LaTeX. Install info for these packages varies with your machine, and can be found here.
Let’s look at running nbconvert from your shell.
From your terminal shell, run jupyter nbconvert --to my_format my_notebook.ipynb.
my_format is one of the conversion options.
my_notebook.ipynb is the name of the file path to your notebook to be converted.
Turn your Jupyter Notebook into pretty HTML with jupyter nbconvert --to html my_notebook.ipynb.
The default output format is a nicely formatted HTML page. If you want a basic HTML version that might be useful for embedding in another HTML document pass --template basic as an argument.
Let’s look at other formats you can convert your notebooks into.
Install LaTeX and Pandoc before attempting these formats. Install info is here.
The respective arguments are pdf, markdown, rst, latex, and asciidoc.
LaTeX files can be exported in one of several different report and article templates described here.
Choosing Markdown, reStructuredText, LaTeX, ASCII output creates a folder with individual .png images from your notebook’s graphics.
I just made a PR to add ASCII conversion to the docs, so soon that functionality will be documented, too.
When inside a Jupyter Notebook, you can run it from the menu or with a keyboard shortcut, of course. I mention this feature because it could be useful as part of a Python script. Just use --to notebook as your argument. There are a few options if you want to try this function, so I recommend you refer to the docs.
Transforming notebooks into slides with --to slides sounds promising, but is not yet a smooth process. You need to manually adjust your Jupyter Notebook cells first. You also need to install the Reveal.js package or have internet access during your slide show. Additionally, you need to set up a server to use slide timings.
I personally wouldn’t use the slides functionality now, but it’s worth revisiting in the future. If you’re so inclined, there is development work to be done on this front. 😄
Let’s look at running nbconvert in a program next.
The ability to easily change from a Jupyter Notebook to a Python script was what made me excited to try nbconvert. And guess what? It works!
jupyter nbconvert --to script my_notebook.ipynb creates my_notebook.py in the same folder. Then you can run python my_notebook.py and smile. 😄
To use the script, you’ll of course need to make sure that the imported packages are available in your environment. Also, heads up that Jupyter magic commands that start with %, %%, or ! will bring your script to a grinding halt, so you’ll need to remove those.
You can write a Python program to use nbconvert as a library. There’s an example here in the docs. A warning that it’s not totally clear what kind of file you need, how to use exporters, or how to write the files.
I used nbconvert in an open source project to make it easy to convert a Jupyter Notebook into a Python executable file and an HTML file. Here’s how to use the NotebookToAll package to create those files with two lines of code.
pip install notebooktoall
from notebooktoall.transform import transform_notebooktransform_notebook(ipynb_file=”my_jupyter_notebook.ipynb”, export_list=[“html”, “py”])
I’m finishing a guide on my experience making an OSS package that uses nbconvert. In it, I’ll show you how you can create your own Python package with automated testing and deployment features. Follow me to make sure you don’t miss it!
If you don’t want to use the command line or the library or my little package, and you’re in Jupyter Notebook, you can download converted files through the View Menu. See the image below.
You lose a little control compared to the command line, but it’s quick. 😏
Update Feb. 27, 2019 Notebooks can be exported from Jupyter Lab, too. Go to File -> Export Notebook As... and choose your export format.
Now you’ve seen the basics of nbconvert. I hope this article has given you some ideas for using it in your work.
If you found this article to be interesting, please share it on your favorite social media channels so that others can find it too! 👏
I write articles about Data Science, Python, Docker, and other tech topics. If you’re interested any of that, check them out here.
Thanks for reading!