Jupyter nbconvert
raw JSON → 7.17.0 verified Tue May 12 auth: no python install: verified quickstart: stale
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 Common errors
error nbconvert failed: xelatex not found on PATH ↓
cause 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.
error nbconvert failed: Pandoc was not found ↓
cause `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. error nbconvert failed: Pyppeteer is not installed to support Web PDF conversion. Please install nbconvert[webpdf] to enable ↓
cause 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. error ModuleNotFoundError: No module named 'notebook.base' ↓
cause 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. error TemplateNotFound: basic.tpl ↓
cause `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). 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.
breaking An `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.
breaking When 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.
Install
conda install nbconvert Install compatibility verified last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) - - 2.42s 50.9M
3.10 slim (glibc) - - 1.66s 47M
3.11 alpine (musl) - - 3.20s 56.9M
3.11 slim (glibc) - - 2.99s 53M
3.12 alpine (musl) - - 3.33s 47.9M
3.12 slim (glibc) - - 3.35s 44M
3.13 alpine (musl) - - 2.71s 47.6M
3.13 slim (glibc) - - 2.39s 44M
3.9 alpine (musl) - - 1.80s 50.6M
3.9 slim (glibc) - - 1.93s 47M
Imports
- HTMLExporter
from nbconvert import HTMLExporter - ExecutePreprocessor
from nbconvert.preprocessors import ExecutePreprocessor - nbformat
import nbformat - Config
from traitlets.config import Config
Quickstart stale last tested: 2026-04-23
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')