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 nbconvertVerified import paths — ran on the pinned version, not inferred.
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.
Always specify the desired output format using `--to <format>` when using the `jupyter nbconvert` command-line tool.
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'.
Ensure your environment uses Python 3.9 or higher. Upgrade Python if necessary.
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.
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.
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.
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.
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 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.
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.
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.
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`.
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`).