Skip to content

Instantly share code, notes, and snippets.

@parente parente/
Last active Sep 5, 2018

What would you like to do?
Jupyter Tidbit: Run a notebook headlessly


You can use nbconvert to execute a notebook from the command line (aka headlessly) and store the results in a new notebook file, an HTML file, a PDF, etc. Tools based on nbconvert, like papermill and nbflow, take this capability a step further and let you easily parameterize and chain notebooks.



The command below executes the notebook named run_me.ipynb and outputs a new notebook file named you_ran_me.ipynb with all cell outputs captured. nbconvert executes the run_me.ipynb notebook using the kernel the notebook document declares in its metadata, python3 in this example.

jupyter nbconvert --to notebook --execute run_me.ipynb --output you_ran_me

Why is this useful?

You can take a notebook you developed in Jupyter Notebook, JupyterLab, nteract, etc., execute it using a scheduler or workflow tool like cron, Jenkins, Airflow, etc., and capture the same rich output in a notebook document as if you ran it manually. See Scheduling Notebooks at Netflix for inspiration.

"cells": [
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"!jupyter nbconvert --to notebook --execute run_me.ipynb --output you_ran_me"
"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.6.5"
"nbformat": 4,
"nbformat_minor": 2
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.