nbconvert

nbconvert converts Jupyter notebook (.ipynb) files into other static formats — HTML, PDF, LaTeX, Markdown, reStructuredText, executable scripts, and reveal.js slideshows — via both a jupyter nbconvert command-line tool and a programmatic Python Exporter API. It can also execute a notebook’s cells before conversion, making it the standard mechanism for turning a live, interactive notebook into a shareable, static artifact.

Beyond direct CLI use, nbconvert’s exporters and Jinja2 templates are consumed as a library by other Jupyter-ecosystem tools — JupyterLab’s export menu, Voila for turning notebooks into standalone web apps, and nbviewer for rendering notebooks as static HTML all build on nbconvert’s conversion pipeline rather than reimplementing it.

What You Get

• jupyter nbconvert CLI to convert notebooks to HTML, PDF, LaTeX, Markdown, reST, scripts, and slides
• A library of format-specific Exporter classes (HTMLExporter, PDFExporter, ScriptExporter, SlidesExporter, etc.) for programmatic use
• An ExecutePreprocessor that runs a notebook’s cells (via the same kernel machinery Jupyter uses) before export
• Jinja2-based, overridable templates for customizing HTML/LaTeX output styling
• A Writer/Postprocessor pipeline for controlling where and how converted output is saved
• A pluggable entrypoint system so third-party packages can register their own custom exporters

Common Use Cases

• Converting a data-analysis notebook into a shareable HTML report or PDF for stakeholders
• Publishing notebook-based tutorials or documentation as static HTML/Markdown on a website
• Re-executing and converting notebooks in CI pipelines to catch broken cells before publishing
• Powering higher-level tools (Voila, nbviewer, JupyterLab’s export menu) that need notebook-to-static-format conversion under the hood

Under The Hood

Architecture - the pipeline is Exporter → Preprocessors → Templates → Writers → Postprocessors: nbconvertapp.py drives the CLI, delegating to one of the format-specific classes under nbconvert/exporters/ (each wrapping a base Exporter that loads the notebook JSON via nbformat, runs a configurable chain of nbconvert/preprocessors/ such as ExecutePreprocessor for cell execution or ClearOutputPreprocessor, renders the result through Jinja2 templates in share/templates/, and hands the output to a Writer in nbconvert/writers/ with optional nbconvert/postprocessors/ like the PDF-via-LaTeX step). Tech Stack - pure Python (~2,900 lines across the exporters alone) built on traitlets for configuration, nbformat for notebook parsing, nbclient/jupyter_client for kernel execution, Jinja2 for templating, Pygments for syntax highlighting, and Pandoc/LaTeX as external tools for certain export formats (PDF, reST); packaged with Hatch (hatch_build.py) and pyproject.toml. Code Quality - the tests/ tree mirrors the source layout with dedicated suites for exporters/, preprocessors/, writers/, postprocessors/, and filters/, plus a fake_exporters.py test double and an exporter_entrypoint test verifying the third-party plugin registration mechanism; the package ships py.typed for typed consumption. API Design - the Exporter base class and its from_notebook_node() method give a consistent, overridable extension point across every output format, and the preprocessor/postprocessor chain is fully configurable via traitlets, letting downstream tools (Voila, JupyterLab) subclass or reconfigure the pipeline rather than needing a parallel implementation.