Jupyter nbconvert: Convert Notebooks to HTML, PDF & Python

How to Convert Jupyter Notebooks with nbconvert

Jupyter nbconvert lets you export .ipynb notebooks to HTML, PDF, Python scripts, Markdown, slides, and more — directly from the command line. This guide covers every format with copy-paste commands and real-world examples.

Jupyter notebooks are fantastic for exploratory work, but eventually you need to share results or reuse your code outside the interactive environment. nbconvert ships with Jupyter and turns notebooks into polished deliverables that you can send to stakeholders, publish to the web, or check into source control.

Just need the file converted? You do not have to install anything. Runcell runs the common conversions in the browser: ipynb → PDF  · ipynb → HTML  · ipynb → Python . Read on if you want to run nbconvert yourself, script it, or batch it.

Hitting an error instead? Go straight to nbconvert PDF Export Errors — the common error messages with their real causes and fixes. If the failure is NoSuchKernel or a ModuleNotFoundError raised by --execute, the problem is which interpreter your kernel starts, not nbconvert: ModuleNotFoundError in Jupyter: A Reproduced Kernel Failure Matrix works through that separately.

Conversion succeeded but the PDF looks wrong? That is a third, quieter failure mode. Jupyter to PDF: A Measured Fidelity Benchmark converts nine probe notebooks through all three export paths and counts what survives: the LaTeX route dropped several non-ASCII characters without reporting a failure, and the browser routes dropped most of a 24-column DataFrame, and the tail of a long source line, off the page edge.

Updated 2026-10-26: the single-notebook commands in the “Export to Python script” section were re-run (the batch wildcards and the pre-commit hook were not). Two earlier claims were wrong — --to script keeps markdown as comments rather than dropping it, and --execute --stdout prints the script, not its output — and the section now says what happens when you run or import the result. “Convert multiple formats at once” was also wrong: --to accepts one format per call.

Prerequisites

• A working Python 3.8+ environment with Jupyter Notebook or JupyterLab installed.
• The notebook you want to convert (analysis.ipynb in the examples below).
• For PDF export, LaTeX must be available on your system (MiKTeX, TeX Live, or MacTeX).

Verify that nbconvert is available:

jupyter nbconvert --version

If the command fails, install it with:

python -m pip install notebook nbconvert

Available conversion formats

nbconvert supports multiple output formats optimized for different use cases:

Let’s explore each format with practical examples.

Export to HTML

Use cases: Sharing analysis with stakeholders, documentation sites, email reports, web dashboards

HTML is the most versatile format for sharing notebook results. It preserves formatting, renders plots, and doesn’t require recipients to have Python installed.

Basic HTML export

jupyter nbconvert analysis.ipynb --to html

This creates analysis.html with all cells, outputs, and embedded images.

For a single file with no local setup, the ipynb → HTML converter  produces the same output in the browser.

HTML with custom styling

# Modern JupyterLab look
jupyter nbconvert analysis.ipynb --to html --template lab
 
# Classic Jupyter Notebook style
jupyter nbconvert analysis.ipynb --to html --template classic
 
# Custom output name
jupyter nbconvert analysis.ipynb --to html --output report.html

Self-contained HTML for email

Create a single HTML file with all images embedded (no external dependencies):

jupyter nbconvert analysis.ipynb --to html --embed-images --output standalone-report.html

This is perfect for emailing reports to clients who need to view results offline.

Hide code cells for stakeholders

When sharing with non-technical audiences, hide the code and show only results:

jupyter nbconvert analysis.ipynb --to html --no-input

Execute before converting

If your notebook has stale outputs, run all cells before exporting:

jupyter nbconvert analysis.ipynb --to html --execute

Batch convert all notebooks

Convert an entire directory of notebooks to HTML:

jupyter nbconvert notebooks/*.ipynb --to html --output-dir build/html

Automate HTML exports

Integrate with CI/CD or task runners. For example, in package.json:

{
  "scripts": {
    "export:html": "jupyter nbconvert notebooks/*.ipynb --to html --execute --output-dir docs/reports"
  }
}

Run with npm run export:html to regenerate reports automatically.

Export to PDF

Use cases: Formal reports, print documentation, client deliverables, academic submissions

PDF exports create professional, print-ready documents with consistent formatting across all platforms.

Basic PDF export (LaTeX method)

jupyter nbconvert analysis.ipynb --to pdf

Requirements: This method requires a LaTeX distribution (TeX Live, MiKTeX, or MacTeX). If you see xelatex not found, install LaTeX first.

PDF without LaTeX (WebPDF method)

Use Chromium headless rendering to avoid LaTeX dependencies:

# Install pyppeteer first
python -m pip install nbconvert[webpdf]
 
# Convert using WebPDF
jupyter nbconvert analysis.ipynb --to webpdf

WebPDF respects modern CSS styling and works on systems without LaTeX.

Hide code for executive reports

Create stakeholder-friendly PDFs showing only outputs:

# Using LaTeX method
jupyter nbconvert analysis.ipynb --to pdf --no-input
 
# Using WebPDF method
jupyter nbconvert analysis.ipynb --to webpdf --no-input

Execute and export to PDF

Run all cells, then create a PDF in one command:

jupyter nbconvert analysis.ipynb --to pdf --execute

Hide specific cells with tags

Tag cells in Jupyter (View > Cell Toolbar > Tags), then exclude them:

# Hide cells tagged with "hide-input"
jupyter nbconvert analysis.ipynb --to pdf \
  --TagRemovePreprocessor.remove_input_tags='["hide-input"]'
 
# Hide cells tagged with "skip"
jupyter nbconvert analysis.ipynb --to pdf \
  --TagRemovePreprocessor.remove_cell_tags='["skip"]'

Custom branding and templates

Create templates/company.tpl for custom headers, logos, or footers:

((*- extends 'article.tplx' -*))
 
((* block header *))
\usepackage{graphicx}
\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyhead[R]{\includegraphics[width=2cm]{logo.png}}
\fancyfoot[C]{Confidential - Company Name}
((* endblock header *))

Then convert with your template:

jupyter nbconvert analysis.ipynb --to pdf --template templates/company.tpl

Export to Python script

Use cases: Version control, module imports, CI/CD pipelines, refactoring into packages

Python exports turn a notebook into a .py file you can diff, import and run outside Jupyter. The single-notebook commands in this section were re-run on 2026-10-26 with nbconvert 7.17.2, Python 3.14.2 and IPython 9.17.1, and the outputs quoted are from that run. The notebooks/*.ipynb batch forms and the pre-commit hook were not run.

Basic Python export

jupyter nbconvert analysis.ipynb --to script

For a Python notebook, --to script and --to python wrote byte-identical files. (--to script picks the extension from the notebook’s language, so it is the one to use for R or Julia notebooks too.) The output keeps markdown cells as # comments and marks each code cell with its execution count:

#!/usr/bin/env python
# coding: utf-8
 
# ## Load data
# Notes for the reader.
 
# In[1]:
 
 
get_ipython().run_line_magic('matplotlib', 'inline')
import pandas as pd

Note the get_ipython() line: nbconvert rewrites every %magic and !command into a call that only exists inside IPython. That matters as soon as you run the file — see Run the generated script below.

The ipynb → Python converter  also keeps markdown as comments and needs no local Jupyter install. It handles magics differently: in a test on 2026-10-26 it copied % and ! lines through unchanged, so a notebook with magics gave a file that python refused to compile (SyntaxError on the %matplotlib inline line). For a notebook without magics that difference does not arise.

Code only, without markdown or cell markers

Markdown and the # In[n]: markers are both on by default. To drop them:

jupyter nbconvert analysis.ipynb --to script \
    --TemplateExporter.exclude_markdown=True --no-prompt

Each flag was checked on its own: exclude_markdown removes the markdown comments, --no-prompt removes the # In[n]: lines, and with both the file is just the code (get_ipython() lines included).

Batch convert notebooks to Python

# Convert all notebooks in a directory
jupyter nbconvert notebooks/*.ipynb --to script --output-dir src/
 
# Re-run each notebook top to bottom first; a notebook whose cells fail is not written
jupyter nbconvert notebooks/*.ipynb --to script --execute --output-dir src/

What --execute checks is narrower than “the script will run”. It re-executes the notebook in a fresh kernel, top to bottom. On a notebook whose cells only worked because they had been run out of order, it exited with code 1 and wrote no .py file — a useful check. But the kernel understands magics, display() and top-level await, so a notebook full of them passes --execute and still produces a script that fails under python.

Use in version control workflows

A pre-commit hook can keep a .py copy next to each notebook for code review:

# .git/hooks/pre-commit
#!/bin/bash
jupyter nbconvert --to script notebooks/*.ipynb --output-dir src/notebooks/
git add src/notebooks/*.py

This is a one-way export: nbconvert’s script does not convert back into the same notebook. If you want a .py you can edit and sync back, that is what jupytext’s paired files are for; ipynb vs py: What Breaks When a Notebook Becomes a Script compares the two, including what a plain re-run does to the .ipynb diff.

Import notebook code as a module

You can import from the converted file, with two things to know first:

# analysis.py was generated from analysis.ipynb
from analysis import process_data

• Importing runs the whole file. Every top-level line of every cell executes on import. In the test, from analysis_mod import process_data printed the notebook’s TOP-LEVEL CELL RAN, rows = 3 line before returning. Move the code you want to reuse into functions, and the cells that do work under if __name__ == "__main__":.
• A get_ipython() line stops the import under plain Python with NameError: name 'get_ipython' is not defined. The test had to delete the %matplotlib inline line before the import worked.

Run the generated script

jupyter nbconvert analysis.ipynb --to script
python analysis.py

If the notebook used any magic, python analysis.py fails on the first get_ipython() line:

NameError: name 'get_ipython' is not defined

Run it with ipython analysis.py instead, which defines get_ipython, or replace the magics with plain Python. Some constructs fail under both — a top-level await is a SyntaxError for the whole file, and a cell’s bare last expression is computed and silently not shown. ipynb vs py: What Breaks When a Notebook Becomes a Script runs twelve such constructs through nbconvert and jupytext under both python and ipython, with the plain-Python replacement for each.

jupyter nbconvert analysis.ipynb --to script --execute --stdout does not run the script: it executes the notebook in a kernel and prints the converted source to stdout (checked: the stdout was the script text, and the program’s own print output did not appear in it).

Export to Markdown

Use cases: GitHub/GitLab documentation, blog posts, static site generators, wiki pages

Markdown exports are perfect for documentation, READMEs, and publishing to platforms that support Markdown.

Basic Markdown export

jupyter nbconvert analysis.ipynb --to markdown

Creates analysis.md with code blocks, outputs, and images extracted to a separate folder.

Embed images inline

Keep images embedded as base64 for single-file portability:

jupyter nbconvert analysis.ipynb --to markdown --NbConvertApp.use_output_suffix=False

Use with static site generators

Convert notebooks for Jekyll, Hugo, or MkDocs:

# For Jekyll blog posts
jupyter nbconvert analysis.ipynb --to markdown --output-dir _posts/
 
# For Hugo content
jupyter nbconvert analysis.ipynb --to markdown --output-dir content/posts/
 
# For MkDocs
jupyter nbconvert analysis.ipynb --to markdown --output-dir docs/

Extract images to custom folder

jupyter nbconvert analysis.ipynb --to markdown --output analysis.md \
  --NbConvertApp.output_files_dir=images/analysis

This creates analysis.md with images stored in images/analysis/.

Export to Reveal.js slides

Use cases: Conference presentations, teaching materials, interactive talks

Create beautiful HTML presentations with slide transitions and speaker notes.

Basic slides export

jupyter nbconvert presentation.ipynb --to slides

Opens in browser with Reveal.js presentation framework.

Serve slides locally

Create and serve the presentation:

jupyter nbconvert presentation.ipynb --to slides --post serve

This automatically opens your browser to view the slideshow.

Control slide structure

In Jupyter, use View > Cell Toolbar > Slideshow to mark cells as:

• Slide - New slide
• Sub-Slide - Vertical slide below current
• Fragment - Appears on click within current slide
• Skip - Hidden from presentation
• Notes - Speaker notes (press ‘s’ during presentation)

Custom slide theme

jupyter nbconvert presentation.ipynb --to slides \
  --SlidesExporter.reveal_theme=serif

Available themes: black, white, league, beige, sky, night, serif, simple, solarized

Export slides with transitions

jupyter nbconvert presentation.ipynb --to slides \
  --SlidesExporter.reveal_transition=zoom \
  --SlidesExporter.reveal_scroll=true

Export to LaTeX

Use cases: Academic papers, journal submissions, custom PDF layouts

LaTeX export gives you full control over document styling for academic publishing.

Basic LaTeX export

jupyter nbconvert paper.ipynb --to latex

Creates paper.tex that you can compile with pdflatex or customize further.

Export with different document classes

# Article format
jupyter nbconvert paper.ipynb --to latex --template article
 
# Report format with chapters
jupyter nbconvert paper.ipynb --to latex --template report

Compile LaTeX to PDF

# Convert to LaTeX
jupyter nbconvert paper.ipynb --to latex
 
# Compile with pdflatex
pdflatex paper.tex

Or combine both steps:

jupyter nbconvert paper.ipynb --to pdf

Export to reStructuredText

Use cases: Sphinx documentation, Python package docs, ReadTheDocs

RST format integrates perfectly with Sphinx documentation systems.

Basic RST export

jupyter nbconvert tutorial.ipynb --to rst

Use in Sphinx documentation

# Convert notebook to RST
jupyter nbconvert tutorial.ipynb --to rst --output-dir docs/source/
 
# Build Sphinx docs
cd docs
make html

Add to your index.rst:

.. toctree::
   :maxdepth: 2
 
   tutorial

Clean or execute notebooks

Use cases: Clear outputs for version control, run all cells before sharing

The notebook-to-notebook conversion is useful for cleaning or executing notebooks.

Clear all outputs

Remove execution results before committing to git:

jupyter nbconvert analysis.ipynb --to notebook --ClearOutputPreprocessor.enabled=True --output analysis.ipynb

Or use the shorthand:

jupyter nbconvert --clear-output --inplace analysis.ipynb

Execute and save results

Run all cells and save the notebook with fresh outputs:

jupyter nbconvert analysis.ipynb --to notebook --execute --output analysis.ipynb

Execute with timeout

Prevent hanging on long-running cells:

jupyter nbconvert analysis.ipynb --to notebook --execute --ExecutePreprocessor.timeout=300 --output analysis.ipynb

This stops execution after 300 seconds per cell.

Advanced techniques

Convert multiple formats at once

--to takes one format per call. Passing several (--to html --to python) exited with code 1 and wrote nothing, with export_format only accepts one value in the error (checked 2026-10-26, nbconvert 7.17.2). Loop instead (run with html and script). For PDF add pdf, which needs the LaTeX install, or webpdf, which needs the Chromium setup from the PDF section above — they are different exporters, and neither was run in this check:

for fmt in html script; do
    jupyter nbconvert report.ipynb --to "$fmt"
done

Use configuration files

Create jupyter_nbconvert_config.py for project-wide settings:

c = get_config()
 
# Always execute before converting
c.NbConvertApp.execute = True
 
# Remove input cells by default
c.TemplateExporter.exclude_input = True
 
# Custom output directory
c.NbConvertApp.output_base = 'converted/'

Run with:

jupyter nbconvert analysis.ipynb --to html --config jupyter_nbconvert_config.py

Extract images and outputs

Extract all images from notebooks:

jupyter nbconvert notebook.ipynb --to markdown

Images are saved in notebook_files/ directory.

Programmatic conversion

Use nbconvert in Python scripts:

import nbformat
from nbconvert import HTMLExporter
 
# Load notebook
with open('analysis.ipynb') as f:
    nb = nbformat.read(f, as_version=4)
 
# Convert to HTML
html_exporter = HTMLExporter()
html_exporter.exclude_input = True
body, resources = html_exporter.from_notebook_node(nb)
 
# Save to file
with open('report.html', 'w') as f:
    f.write(body)

Troubleshooting common issues

PDF export errors — see the dedicated reference

PDF export is where nbconvert fails most often, and the error text is frequently misleading. PandocMissing, xelatex not found on PATH, missing .sty files, Playwright errors on --to webpdf, and CJK font problems each have a different cause, and the missing-package errors from LaTeX end with a line reference that sends most people looking at the wrong package.

Those are all covered — with the real terminal output and the actual cause — in nbconvert PDF Export Errors: A Complete Troubleshooting Reference.

If you just need the PDF and would rather not debug a LaTeX install, convert it in the browser  instead.

Missing packages or templates

Error: TemplateNotFound: lab.tpl

Solution: Update nbconvert and notebook:

python -m pip install --upgrade nbconvert notebook

Execution timeout

Error: Timeout waiting for execute reply

Solution: Increase timeout or skip execution:

# Increase timeout to 10 minutes
jupyter nbconvert notebook.ipynb --to html --execute --ExecutePreprocessor.timeout=600
 
# Skip problematic cells by tagging them 'skip' in Jupyter
jupyter nbconvert notebook.ipynb --to html --execute --TagRemovePreprocessor.remove_cell_tags='["skip"]'

Images not displaying

Problem: External images don’t show in HTML/PDF exports

Solution: Use --embed-images flag or store images in the same directory:

jupyter nbconvert notebook.ipynb --to html --embed-images

Interactive widgets not working

Problem: IPywidgets appear as empty boxes in HTML

Solution: Use the --no-input flag to hide widget code, or embed widget state:

jupyter nbconvert notebook.ipynb --to html --template lab

For interactive widgets, consider using Voilà or JupyterBook instead.

Memory errors on large notebooks

Problem: Conversion fails on notebooks with large outputs

Solution: Clear outputs first, then re-execute selectively:

# Clear all outputs
jupyter nbconvert --clear-output --inplace notebook.ipynb
 
# Execute only specific cells manually, then convert
jupyter nbconvert notebook.ipynb --to html

Automated exports

Set up scheduled exports with cron (Linux/macOS):

# crontab -e
# Run daily at 2 AM
0 2 * * * cd /path/to/project && jupyter nbconvert notebooks/*.ipynb --to html --execute --output-dir reports/

Or use GitHub Actions:

name: Export Notebooks
on:
  push:
    paths:
      - 'notebooks/**'
jobs:
  convert:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - run: pip install jupyter nbconvert
      - run: jupyter nbconvert notebooks/*.ipynb --to html --output-dir docs/
      - uses: actions/upload-artifact@v3
        with:
          name: converted-notebooks
          path: docs/

Quick reference

Summary

With nbconvert, you can transform Jupyter notebooks into professional deliverables for any audience. Whether you’re creating executive reports with hidden code, publishing documentation to ReadTheDocs, generating slide presentations, or integrating notebooks into CI/CD pipelines, nbconvert provides the flexibility you need. Start with the basic commands above, then explore templates, configuration files, and programmatic conversion as your workflow demands more customization.