# Convert a Jupyter notebook to a standalone HTML report

Canonical: https://githtml.com/guides/convert-jupyter-notebook-to-html
Published: 2026-10-10
Publisher: WaveTech LLC / gitHtml

Run jupyter nbconvert --to html notebook.ipynb to produce an HTML file. Plot outputs stored in the notebook are already embedded as data URIs; add --embed-images for images referenced from Markdown cells and --no-input for a code-free report. The default templates still load require.js and MathJax from a CDN, so check those before reading offline.

## The basic conversion

nbconvert ships with Jupyter and converts a notebook into another format using a template. For HTML, the default lab template produces a full static render that looks like JupyterLab. The output reflects whatever outputs are saved in the notebook, so a notebook committed without outputs produces a report of code cells and empty space.

Use --execute when you want nbconvert to run the notebook first. That makes the report reproducible from the source, but it also means the conversion needs the same data files, environment, and credentials the notebook needs. For a review artifact, executing deliberately on your machine and committing the HTML is often simpler than expecting readers to rerun it.

````bash
# Convert with saved outputs
jupyter nbconvert --to html analysis.ipynb

# Re-run first, hide code, embed Markdown-cell images
jupyter nbconvert --to html --execute --no-input --embed-images analysis.ipynb

# Minimal markup with no CDN scripts in the head
jupyter nbconvert --to html --template basic analysis.ipynb
````

## What is embedded and what is not

Image outputs such as matplotlib PNG charts are written into the HTML as base64 data URIs, so they travel with the file. Images you referenced in Markdown cells, like a diagram saved next to the notebook, are linked by path unless you pass --embed-images. The nbconvert configuration documents that option as embedding images in Markdown cells.

Scripts are a different story. In current nbconvert source, the lab and classic templates include a require.js script and MathJax from cdnjs by default, and load a widget manager from unpkg only when the notebook contains widget state. Exporter options such as HTMLExporter.mathjax_url and HTMLExporter.require_js_url let you point those to files you host, and the basic template omits them.

## Prepare the notebook for readers

A notebook written for exploration rarely reads well as a report. Spend five minutes shaping it before conversion: readers want the question, the method, the result, and the caveats in that order, with the plumbing out of the way.

1. Add a first Markdown cell with the question, data source, date, and conclusion.
2. Delete dead-end cells and long debug printouts, or move them to an appendix notebook.
3. Give every chart a title and axis labels, and add one sentence below it explaining what it shows.
4. Restart the kernel and run all cells so outputs match the code order.
5. Convert, then open the HTML with scripts disabled to confirm the text and charts remain.

## Commit and read the result

Commit the HTML next to the notebook with a name that says it is a rendered copy, for example analysis.report.html, and mention the notebook revision in the first cell. Large embedded images make files heavy; downsample charts that do not need print resolution.

In gitHtml, the report opens like any other repository HTML file. Because JavaScript is off by default, the parts that depend on MathJax will show raw TeX until scripts are allowed for that document; static text, tables, and embedded charts read normally.

## Sources and further reading

- [nbconvert: Using as a command line tool](https://nbconvert.readthedocs.io/en/latest/usage.html)
- [nbconvert: Configuration options](https://nbconvert.readthedocs.io/en/latest/config_options.html)
- [nbconvert source: HTML exporter defaults](https://github.com/jupyter/nbconvert/blob/main/nbconvert/exporters/html.py)

## Related guides

- [Build a single-file HTML document that travels well](https://githtml.com/guides/portable-single-file-html-document)
- [Recover a chart that disappears when scripts are disabled](https://githtml.com/guides/javascript-chart-missing-html)
- [Decide which images belong inside a portable HTML report](https://githtml.com/guides/images-in-portable-html)
- [HTML vs Markdown for technical documents: how to choose](https://githtml.com/guides/html-vs-markdown-for-technical-documents)

Editorial approach: https://githtml.com/guides/about