Create a gist now

Instantly share code, notes, and snippets.

What would you like to do?
run and validate a notebook
#!/usr/bin/env python
simple example script for running notebooks and reporting exceptions.
Usage: ` foo.ipynb [bar.ipynb [...]]`
Each cell is submitted to the kernel, and checked for errors.
import os,sys,time
from Queue import Empty
from IPython.kernel import KernelManager
except ImportError:
from IPython.zmq.blockingkernelmanager import BlockingKernelManager as KernelManager
from IPython.nbformat.current import reads, NotebookNode
def run_notebook(nb):
km = KernelManager()
km.start_kernel(stderr=open(os.devnull, 'w'))
kc = km.client()
except AttributeError:
# 0.13
kc = km
shell = kc.shell_channel
# simple ping:
cells = 0
failures = 0
for ws in nb.worksheets:
for cell in ws.cells:
if cell.cell_type != 'code':
# wait for finish, maximum 20s
reply = shell.get_msg(timeout=20)['content']
if reply['status'] == 'error':
failures += 1
print "\nFAILURE:"
print cell.input
print '-----'
print "raised:"
print '\n'.join(reply['traceback'])
cells += 1
print "ran notebook %s" %
print " ran %3i cells" % cells
if failures:
print " %3i cells raised exceptions" % failures
del km
if __name__ == '__main__':
for ipynb in sys.argv[1:]:
print "running %s" % ipynb
with open(ipynb) as f:
nb = reads(, 'json')

hugadams commented Jun 5, 2014

If I have a notebook that has cells ready to be run (say they produce plots form an experiment), and I run this on that notebook, when I open the notebook, the output is still note created. Is it possible to run the notebook offline, and then overwrite the nb with the newly run version?

@hugadams I had the same question, and I discovered this:

Neither the above code, nor runipy, seem to run actually run an IPython notebook as the notebook itself runs it: if I have a "%load" directive in a notebook, and I run all the cells via the interactive menu, the "%load" magic loads the code in a new cell, and this cell is then executed. On the opposite, the various headless runners that I have found just skip the new cell.

It would be really useful to be able to run notebook headless. Currently it is hard to do quality assurance on notebooks.

zonca commented May 11, 2015

@minrk would it be possible to update this script for IPython 3?

twiecki commented Aug 4, 2015

@minrk Second that request. Tried to run but got a:

AttributeError: 'ZMQSocketChannel' object has no attribute 'execute'

@minrk I got the same error as @twiecki. AttributeError: 'ZMQSocketChannel' object has no attribute 'execute' am I missing something?

@twiecki @kayhan-batmanghelich did you fix the issue?

brunsgaard commented Mar 16, 2017

Our solution

import os
import glob
import time
import sys
import traceback

import nbconvert
import nbformat

ep = nbconvert.preprocessors.ExecutePreprocessor(

def run_notebook(path):
    path = os.path.abspath(path)
    assert path.endswith('.ipynb')
    nb =, as_version=4)
        ep.preprocess(nb, {'metadata': {'path': os.path.dirname(path)}})
    except Exception as e:
        print("\nException raised while running '{}'\n".format(path))

if __name__ == '__main__':
    print('Running notebooks might take a long time...')
    for path in glob.iglob('notebooks/**/*.ipynb', recursive=True):
        root, ext = os.path.splitext(os.path.basename(path))
        if root.endswith('_'):
        s = time.time()
        sys.stdout.write('Now running ' + path)
        sys.stdout.write(' -- Finish in {}s\n'.format(int(time.time()-s)))

      ' Notebook testing done '
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment