Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 39 ยท Collaboration and Deployment

Exporting Notebooks with nbconvert

Convert notebooks to HTML, PDF, Markdown, slides and Python scripts with jupyter nbconvert, execute them headlessly, hide code or inputs, and use templates in automated builds.

A notebook is a great working document and an awkward delivery format. Your manager wants a PDF, the website needs HTML, your pipeline needs a script, and a presentation needs slides. nbconvert is the command-line tool that turns a notebook into all of these, and it can also run the notebook first, which makes it the simplest way to automate a report.

nbconvert is not available on this site, so the commands below are read-only and the output is described. The runnable cells reproduce the core idea, converting the notebook's JSON into Markdown and a script, with plain Python.

Basic conversions

Terminal
pip install nbconvert
jupyter nbconvert --to html notebook.ipynb         # notebook.html
jupyter nbconvert --to pdf notebook.ipynb          # needs a LaTeX install (or use webpdf)
jupyter nbconvert --to markdown notebook.ipynb     # notebook.md plus an images folder
jupyter nbconvert --to script notebook.ipynb       # notebook.py
jupyter nbconvert --to slides notebook.ipynb --post serve
jupyter nbconvert --to rst notebook.ipynb

The new file lands next to the notebook. Use --output-dir=build to place it elsewhere and --output report to choose the base name. You can convert several notebooks with a glob: jupyter nbconvert --to html notebooks/*.ipynb.

For PDF there are two routes. The default builds LaTeX and runs a TeX engine, so it needs TeX Live or MiKTeX installed. --to webpdf renders the HTML with a headless Chromium, which needs only pip install "nbconvert[webpdf]" and a one-time browser download, and its output looks like the web page.

Execute before converting

An .ipynb file that is committed without outputs would turn into an empty-looking report. Tell nbconvert to run it:

Terminal
jupyter nbconvert --to html --execute notebook.ipynb
jupyter nbconvert --to notebook --execute --inplace notebook.ipynb
jupyter nbconvert --execute --ExecutePreprocessor.timeout=600 --to html notebook.ipynb
jupyter nbconvert --execute --allow-errors --to html notebook.ipynb

--execute starts a kernel, runs every cell top to bottom, and then converts. This is exactly "Restart and Run All" without the interface (see hidden state). If a cell raises an error the conversion stops with a non-zero exit code, which makes --execute a convenient test in CI: a notebook that does not run fails the pipeline. --allow-errors keeps going and shows the traceback in the output, handy for teaching material that fails on purpose.

Set a longer timeout for slow cells (the default is 30 seconds per cell) and choose the kernel with --ExecutePreprocessor.kernel_name=python3.

Hiding code or inputs

A report for non-programmers should show results, not code.

Terminal
jupyter nbconvert --to html --no-input notebook.ipynb          # hide all code cells' input
jupyter nbconvert --to html --no-prompt notebook.ipynb         # remove In[ ]/Out[ ] labels
jupyter nbconvert --to html --TagRemovePreprocessor.enabled=True \
  --TagRemovePreprocessor.remove_cell_tags='{"hide-cell"}' notebook.ipynb

Tags give per-cell control. Add a tag such as remove_input, remove_output or remove_cell in the cell's metadata (View, Cell Toolbar, Tags in older interfaces; the Property Inspector in JupyterLab), and the corresponding conversion drops that part of the cell. Use these tags for setup cells and noisy debug printing.

The pipeline in miniature

flowchart LR
  A[".ipynb"] --> B["Execute (optional)"]
  B --> C["Preprocessors: tags, clear, filter"]
  C --> D["Exporter: html, pdf, markdown, script"]
  D --> E["Writer: files"]

Each stage is a replaceable component, which is why nbconvert can be extended with custom preprocessors.

A tiny exporter in Python

Under the hood, an exporter walks the cell list and renders each one. This cell does the same for Markdown and for a script, so you can see how little magic there is.

Python Export a notebook to Markdown and a script

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The cell with the remove_cell tag disappears from the Markdown but remains in the script, just as nbconvert's tag preprocessors affect only the exporters that use them.

Templates and configuration

HTML output uses a template (--template classic or lab, the default). Tweaking the look can be done with a custom template folder or with CSS. Repeated options belong in a config file, jupyter_nbconvert_config.py:

Python
c = get_config()
c.NbConvertApp.export_format = "html"
c.ExecutePreprocessor.timeout = 600
c.TemplateExporter.exclude_input_prompt = True

You can also call nbconvert from Python (nbconvert.HTMLExporter, ExecutePreprocessor) to build a report generator that loops over many notebooks. For parameterized runs of one notebook with different inputs, see Papermill.

Practical advice

  • Run --execute in a clean environment (CI or a container) so the output reflects the pinned requirements.
  • Convert to HTML for sharing: one self-contained file, images embedded.
  • Exports are snapshots. Do not edit them by hand; regenerate.
  • Keep secrets out of notebooks, because exports copy everything including outputs (see notebook security).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command converts a notebook to a Python script?

    --to script picks the exporter for the kernel's language, here a .py file.
  2. 2. What does --execute do?

    The notebook is executed top to bottom first, so the export contains up-to-date outputs.
  3. 3. How do you hide the code of selected cells in an HTML export?

    Cell tags with TagRemovePreprocessor remove inputs, outputs or whole cells.
  4. 4. Why is --execute useful in CI?

    Execution errors stop the conversion and return an error status.

Summary

  • jupyter nbconvert --to html|pdf|markdown|script|slides exports notebooks.
  • --execute runs the notebook first and doubles as a CI check.
  • Hide code with --no-input or per-cell tags; set a timeout for slow cells.
  • An exporter is just a walk over the cell list, so you can script your own.

Next: Parameterized Runs with Papermill