Jupyter nbconvert

Warnings

• breaking The default output format for the `jupyter nbconvert` command-line tool changed in version 6.0. Previously, HTML was the default, but now the `--to` argument is explicitly required (e.g., `--to html`).
  Fix: Always specify the desired output format using `--to <format>` when using the `jupyter nbconvert` command-line tool.
• breaking The custom template system was overhauled in nbconvert 6.0. Older `.tpl` template files from 5.x are no longer directly compatible with the `--template` argument. New templates are package-installable with a `conf.json` structure.
  Fix: Migrate custom templates to the new package-based system or use `--template-file path/to/old/file.tpl` for backward compatibility with old `.tpl` files. Consult the official documentation on 'Creating Custom Templates'.
• breaking Python 2 support was officially dropped in nbconvert 6.0. The library now requires Python 3.6+ (for 6.x) and specifically Python 3.9+ for version 7.x.
  Fix: Ensure your environment uses Python 3.9 or higher. Upgrade Python if necessary.
• gotcha Converting to certain formats like PDF (via LaTeX) or WebPDF, or to formats requiring complex markdown rendering, has external dependencies (e.g., Pandoc, TeX/XeLaTeX, Playwright/Chromium) that are not installed by default with `pip install nbconvert`.
  Fix: Manually install these external tools (e.g., `sudo apt-get install pandoc` or `pip install nbconvert[webpdf]`) according to the nbconvert documentation for the specific output format you need.
• gotcha When converting a notebook to an executable Python script (`--to script`), Jupyter magic commands (starting with `%`, `%%`, or `!`) are not standard Python and will cause the resulting `.py` script to fail if executed outside of an IPython environment.
  Fix: Before converting to a Python script, manually remove or comment out any Jupyter magic commands in the notebook cells, or use an IPython environment to run the generated script.
• breaking nbconvert 6.0 introduced incompatibilities with `nbgrader`'s `generate_feedback` functionality, specifically with its `HTMLExporter`.
  Fix: If using `nbgrader` with nbconvert 6.0, pin `nbconvert` to version `5.6.1` or consult `nbgrader`'s documentation for compatibility with later nbconvert versions.

Install

• pip install nbconvert PyPI
• conda install nbconvert Conda

Imports

• HTMLExporter

  from nbconvert import HTMLExporter

• ExecutePreprocessor

  from nbconvert.preprocessors import ExecutePreprocessor

• nbformat

  import nbformat

  Often used alongside nbconvert for loading/saving notebook nodes.
• Config

  from traitlets.config import Config

  Used for advanced configuration of exporters and preprocessors.

Quickstart

This quickstart demonstrates how to programmatically load, optionally execute, and then convert a Jupyter notebook to HTML using nbconvert's Python API. It creates a dummy notebook for a runnable example.

import nbformat
from nbconvert.preprocessors import ExecutePreprocessor
from nbconvert.exporters import HTMLExporter
import os

# Create a dummy notebook file for demonstration
notebook_content = {
    "cells": [
        {"cell_type": "code", "source": "a = 1\nb = 2\nprint(a + b)", "metadata": {}} 
    ],
    "metadata": {"kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"}, "language_info": {"codemirror_mode": {"name": "ipython", "version": 3}, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.9.0"}},
    "nbformat": 4,
    "nbformat_minor": 5
}

notebook_filename = "my_notebook.ipynb"
with open(notebook_filename, 'w', encoding='utf-8') as f:
    nbformat.write(nbformat.from_dict(notebook_content), f)

# 1. Load the notebook
with open(notebook_filename, 'r', encoding='utf-8') as f:
    nb = nbformat.read(f, as_version=4)

# 2. (Optional) Execute the notebook
ep = ExecutePreprocessor(timeout=600, kernel_name='python3')
tried_nb, _ = ep.preprocess(nb, {'metadata': {'path': '.'}})

# 3. Convert to HTML
html_exporter = HTMLExporter()
body, resources = html_exporter.from_notebook_node(tried_nb)

# 4. Save the converted file
output_filename = "my_notebook.html"
with open(output_filename, 'w', encoding='utf-8') as f:
    f.write(body)

print(f"Notebook '{notebook_filename}' executed and converted to '{output_filename}'")

# Clean up the dummy notebook file
os.remove(notebook_filename)
if os.path.exists('my_notebook.nbconvert.ipynb'): # Preprocessor might save an executed version
    os.remove('my_notebook.nbconvert.ipynb')