{"id":539,"library":"nbconvert","title":"Jupyter nbconvert","description":"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.","status":"active","version":"7.17.0","language":"python","source_language":"en","source_url":"https://github.com/jupyter/nbconvert","tags":["jupyter","notebook","conversion","html","pdf","latex","markdown","exporter","cli","library","tool"],"install":[{"cmd":"pip install nbconvert","lang":"bash","label":"PyPI"},{"cmd":"conda install nbconvert","lang":"bash","label":"Conda"}],"dependencies":[{"reason":"Required for converting notebooks to LaTeX, reStructuredText, and other non-HTML markdown formats.","package":"pandoc","optional":true},{"reason":"Required for PDF conversion using the LaTeX-based method. This includes packages like MacTeX on macOS or Latex Project on Windows.","package":"TeX (specifically XeLaTeX)","optional":true},{"reason":"Required for WebPDF conversion, which uses a headless Chromium browser for rendering.","package":"playwright","optional":true},{"reason":"Core dependency for reading and writing Jupyter notebook files.","package":"jupyter-nbformat","optional":false},{"reason":"Used for executing notebooks programmatically, especially since nbconvert 6.0.","package":"nbclient","optional":false}],"imports":[{"symbol":"HTMLExporter","correct":"from nbconvert import HTMLExporter"},{"symbol":"ExecutePreprocessor","correct":"from nbconvert.preprocessors import ExecutePreprocessor"},{"note":"Often used alongside nbconvert for loading/saving notebook nodes.","symbol":"nbformat","correct":"import nbformat"},{"note":"Used for advanced configuration of exporters and preprocessors.","symbol":"Config","correct":"from traitlets.config import Config"}],"quickstart":{"code":"import nbformat\nfrom nbconvert.preprocessors import ExecutePreprocessor\nfrom nbconvert.exporters import HTMLExporter\nimport os\n\n# Create a dummy notebook file for demonstration\nnotebook_content = {\n    \"cells\": [\n        {\"cell_type\": \"code\", \"source\": \"a = 1\\nb = 2\\nprint(a + b)\", \"metadata\": {}} \n    ],\n    \"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\"}},\n    \"nbformat\": 4,\n    \"nbformat_minor\": 5\n}\n\nnotebook_filename = \"my_notebook.ipynb\"\nwith open(notebook_filename, 'w', encoding='utf-8') as f:\n    nbformat.write(nbformat.from_dict(notebook_content), f)\n\n# 1. Load the notebook\nwith open(notebook_filename, 'r', encoding='utf-8') as f:\n    nb = nbformat.read(f, as_version=4)\n\n# 2. (Optional) Execute the notebook\nep = ExecutePreprocessor(timeout=600, kernel_name='python3')\ntried_nb, _ = ep.preprocess(nb, {'metadata': {'path': '.'}})\n\n# 3. Convert to HTML\nhtml_exporter = HTMLExporter()\nbody, resources = html_exporter.from_notebook_node(tried_nb)\n\n# 4. Save the converted file\noutput_filename = \"my_notebook.html\"\nwith open(output_filename, 'w', encoding='utf-8') as f:\n    f.write(body)\n\nprint(f\"Notebook '{notebook_filename}' executed and converted to '{output_filename}'\")\n\n# Clean up the dummy notebook file\nos.remove(notebook_filename)\nif os.path.exists('my_notebook.nbconvert.ipynb'): # Preprocessor might save an executed version\n    os.remove('my_notebook.nbconvert.ipynb')","lang":"python","description":"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."},"warnings":[{"fix":"Always specify the desired output format using `--to <format>` when using the `jupyter nbconvert` command-line tool.","message":"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`).","severity":"breaking","affected_versions":">=6.0.0"},{"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'.","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Ensure your environment uses Python 3.9 or higher. Upgrade Python if necessary.","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"nbconvert 6.0 introduced incompatibilities with `nbgrader`'s `generate_feedback` functionality, specifically with its `HTMLExporter`.","severity":"breaking","affected_versions":"6.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T14:48:44.687Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"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.","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.","error":"nbconvert failed: xelatex not found on 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.","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.","error":"nbconvert failed: Pandoc was not found"},{"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.","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.","error":"nbconvert failed: Pyppeteer is not installed to support Web PDF conversion. Please install nbconvert[webpdf] to enable"},{"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`.","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.","error":"ModuleNotFoundError: No module named 'notebook.base'"},{"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`).","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.","error":"TemplateNotFound: basic.tpl"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.42,"mem_mb":24.7,"disk_size":"50.9M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.66,"mem_mb":24.7,"disk_size":"47M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.2,"mem_mb":27.3,"disk_size":"56.9M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.99,"mem_mb":27.3,"disk_size":"53M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.33,"mem_mb":26.8,"disk_size":"47.9M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.35,"mem_mb":26.8,"disk_size":"44M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.71,"mem_mb":27.4,"disk_size":"47.6M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.39,"mem_mb":27.4,"disk_size":"44M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.8,"mem_mb":26.9,"disk_size":"50.6M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.93,"mem_mb":26.9,"disk_size":"47M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}