Registry / data / nbconvert

nbconvert

JSON →
library7.17.1pypypi✓ verified 25d ago

nbconvert is a powerful tool in the Jupyter ecosystem that converts Jupyter Notebook files (.ipynb) into various other static formats like HTML, LaTeX, PDF, Markdown, reStructuredText, and executable scripts. It is actively maintained and currently supports Python 3.9-3.12. The library sees regular updates, often with several minor releases within major versions.

pip install nbconvert
INSTALL
IMPORT
SIG · NBCONVERT
N
nbconvert
datapythonv7.17.1
Install
6.7s avg
Import
1582ms
Disk
50MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v7.17.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.618s · 52.2MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 6.7s · import 1.546s · 48MB
50MB installed
● package 50MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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')
jupyter-nbconvert --version
Debug
Known issues
breakingThe 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.
affects: >=6.0.0
breakingThe 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'.
affects: >=6.0.0
breakingPython 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.
affects: >=6.0.0
gotchaConverting 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.
affects: All versions
gotchaWhen 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.
affects: All versions
breakingnbconvert 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.
affects: 6.0.0
breakingAn `AttributeError: outputs` occurs when `nbformat` attempts to process a notebook cell that lacks the required 'outputs' attribute. This indicates a malformed notebook structure, typically when a code cell is missing its `outputs` key.
fix
Ensure all notebook cells, especially code cells, include an 'outputs' key (e.g., `cell.outputs = []`) in their data structure. Validate the notebook dictionary against the `nbformat` schema using `nbformat.validate()` before attempting to write it.
affects: All versions
breakingWhen programmatically creating or manipulating notebook structures as dictionaries before writing them with `nbformat.write` (especially using `nbformat.from_dict`), ensure that all cells, particularly code cells, contain an 'outputs' key with a list value (e.g., `[]`), even if empty. Missing this key for any cell will result in an `AttributeError: outputs` during serialization.
fix
Review the input dictionary structure for the notebook to ensure every cell object includes an 'outputs' key, initialized as an empty list if there are no specific outputs to record. Refer to the nbformat specification for the expected structure of notebook cells.
affects: All versions
Errors
Common errors & fixes
nbconvert failed: xelatex not found on PATH
Converting notebooks to PDF via LaTeX requires a full TeX distribution (like MiKTeX on Windows, MacTeX on macOS, or TeX Live on Linux) to be installed and its executables, specifically `xelatex`, to be accessible in the system's PATH environment variable.
fix
Install a full TeX distribution appropriate for your operating system (e.g., MiKTeX for Windows, MacTeX for macOS, or TeX Live for Linux) and ensure its binary directory is added to your system's PATH. Restart your Jupyter server or terminal after installation.
nbconvert failed: Pandoc was not found
`nbconvert` relies on Pandoc for converting notebooks to various markdown-based formats, including an intermediate step for PDF via LaTeX. This error occurs if Pandoc is not installed or is not correctly located in the system's PATH.
fix
Install Pandoc. On Debian/Ubuntu, use `sudo apt-get install pandoc`. On macOS, use `brew install pandoc`. For other platforms, download and install from the official Pandoc website. Ensure the Pandoc executable is in your system's PATH.
nbconvert failed: Pyppeteer is not installed to support Web PDF conversion. Please install nbconvert[webpdf] to enable
When attempting to export a notebook to PDF using the 'WebPDF' exporter (which leverages a headless browser), the `playwright` (or older `pyppeteer`) package and its Chromium browser dependencies are missing from your Python environment.
fix
Install `nbconvert` with the `webpdf` extra: `pip install "nbconvert[webpdf]"`. This command installs `playwright`, which then automatically handles the download of the necessary browser binaries.
ModuleNotFoundError: No module named 'notebook.base'
This error typically indicates a version incompatibility between `nbconvert` and its Jupyter dependencies, such as the `notebook` package, particularly with `nbconvert` versions that are not compatible with Jupyter Notebook 7+ where the `notebook.base` module structure changed.
fix
Ensure all Jupyter-related packages (`jupyterlab`, `notebook`, `nbconvert`, `ipykernel`) are up-to-date and installed within the same Python environment. You can upgrade them using: `pip install --upgrade jupyterlab notebook nbconvert ipykernel` or `conda update --all`.
TemplateNotFound: basic.tpl
`nbconvert` version 6.0 and later introduced significant changes to how templates are handled, moving from single `.tpl` files to a directory-based structure. Older commands or custom templates designed for `nbconvert` 5.x that refer to templates like `basic.tpl` directly will fail with newer versions.
fix
For older `.tpl` templates, explicitly specify the full path using the `--template-file` argument: `jupyter nbconvert --to html --template-file /path/to/my_template.tpl`. If using a custom template, ensure it adheres to the `nbconvert 6.x+` template directory structure, which includes a `conf.json` file. For built-in templates, use their updated names (e.g., `classic`, `lab`).
Upgrade
Version history
7.17.1latest on PyPI · released Apr 8, 2026
Audit
Dependencies
pandocoptionalRequired for converting notebooks to LaTeX, reStructuredText, and other non-HTML markdown formats.
TeX (specifically XeLaTeX)optionalRequired for PDF conversion using the LaTeX-based method. This includes packages like MacTeX on macOS or Latex Project on Windows.
playwrightoptionalRequired for WebPDF conversion, which uses a headless Chromium browser for rendering.
jupyter-nbformatrequiredCore dependency for reading and writing Jupyter notebook files.
nbclientrequiredUsed for executing notebooks programmatically, especially since nbconvert 6.0.
Agent activity
13 hits · last 30 days
node
12
Resources
nbconvert — pip install nbconvert · libregistry