Introduction to nbconvert
Jupyter nbconvert is a powerful tool that allows users to convert Jupyter Notebooks (.ipynb files) into various static formats such as HTML, PDF, Markdown, and more. It is an essential utility for sharing, publishing, and automating workflows around Jupyter Notebooks. This blog post will guide you through the most useful APIs and provide real-life examples to help you leverage nbconvert effectively.
Getting Started with nbconvert
To begin using nbconvert, ensure it’s installed. It typically comes pre-installed with Jupyter, but you can also install it using pip:
pip install nbconvert
Once installed, you can use nbconvert via the command line or through its Python API.
Conversion Formats and Examples
1. Converting to HTML
You can convert a notebook to an HTML file with the following command:
jupyter nbconvert --to html my_notebook.ipynb
To achieve the same programmatically using Python:
from nbconvert import HTMLExporter
from nbformat import read, write
from nbformat.v4 import new_notebook
# Load your notebook
with open("my_notebook.ipynb") as f:
notebook = read(f, as_version=4)
# Export to HTML
html_exporter = HTMLExporter()
html_content, _ = html_exporter.from_notebook_node(notebook)
# Save the HTML content
with open("my_notebook.html", "w") as f:
f.write(html_content)
2. Converting to PDF
Exporting to PDF is often used for sharing. Use the command line:
jupyter nbconvert --to pdf my_notebook.ipynb
Or programmatically:
from nbconvert import PDFExporter
pdf_exporter = PDFExporter()
pdf_content, _ = pdf_exporter.from_notebook_node(notebook)
with open("my_notebook.pdf", "wb") as f:
f.write(pdf_content)
3. Converting to Markdown
Creating documentation from notebooks is easy by converting them to Markdown format:
jupyter nbconvert --to markdown my_notebook.ipynb
Python API equivalent:
from nbconvert import MarkdownExporter
markdown_exporter = MarkdownExporter()
markdown_content, _ = markdown_exporter.from_notebook_node(notebook)
with open("my_notebook.md", "w") as f:
f.write(markdown_content)
4. Executing a Notebook during Conversion
If you want to execute the notebook while converting, use the --execute flag:
jupyter nbconvert --to html --execute my_notebook.ipynb
Programmatically, use ExecutePreprocessor:
from nbconvert.preprocessors import ExecutePreprocessor
executor = ExecutePreprocessor(timeout=600, kernel_name="python3")
executor.preprocess(notebook, {'metadata': {'path': './'}}) # Modify this to the notebook's directory
Combining nbconvert APIs to Build Applications
Below is a simple Flask app example that serves notebook content as rendered HTML:
from flask import Flask, render_template_string
from nbconvert import HTMLExporter
from nbformat import read
app = Flask(__name__)
@app.route('/render-notebook')
def render_notebook():
# Load and render a notebook
with open("my_notebook.ipynb") as f:
notebook = read(f, as_version=4)
exporter = HTMLExporter()
html_content, _ = exporter.from_notebook_node(notebook)
# Render the HTML in a simple template
template = "<!DOCTYPE html><html><body>{{ content|safe }}</body></html>"
return render_template_string(template, content=html_content)
if __name__ == "__main__":
app.run(debug=True)
This application demonstrates how to integrate nbconvert into a web framework for dynamic notebook rendering.
Conclusion
Jupyter nbconvert is a versatile tool that extends the usability of your notebooks. Whether you’re looking to publish notebooks in static formats, execute them programmatically, or integrate them into larger applications, nbconvert offers the functionality you need. We hope this guide and its examples help you harness the power of nbconvert in your workflows.
