A lean utility to run the jupyter notebooks from commandline with stdout outputs
runnb - The run-notebook script
runnb is a script to run
jupyter notebooks from the command-line.
It is a
nbconvert API wrapper.
Notes on executing notebooks can be found here.
You may also want to see the format specification of
Current version of
runnb is implemented and tested under
python 2, 3 and
To install pip package,
pip install runnb
or to install latest version,
pip install --upgrade git+https://github.com/InnovArul/runnb
runnb [options] <path/to/notebook.ipynb>
- -h --help Display help message.
- -e --allow-error Allow error during single cell and continue running.
- -n --no-stdio Don't recover STDIO to command line. (You may not see printed messages.)
- -a --allow-not-trusted Run the notebook even not trusted.
- -t --to=<path/to/notebook.out.ipynb> Save the executed notebook to a specific file.
Assume we have a notebook
Simply run the notebook from command-line:
If we want to run the notebook not being break by possible error in some cell, pass the
runnb --allow-error test.ipynb
Or do it with the shortcut
runnb -e test.ipynb
If we wanted to export the executed notebook, use
runnb --to=test.out.ipynb test.ipynb
or using its shortcut
runnb --ttest.out.ipynb test.ipynb
By default, we recover the output of notebook to the command-line by boardcasting the
error stream. This is done by adding a small snippet of code handling
sys.stderr. A tiny
Tee Class is used to support such behavior. Make sure
tee.py is in our python search path. If doing this is not preferable in certain scenario, we can turn it off by passing
runnb --no-stdio test.ipynb
or using its shortcut
runnb -n test.ipynb
However, this could mean we may not see output from the execution on the command-line. It could be a good idea to save those outputs to a output notebook by using
runnb --no-stdio --to test.out.ipynb test.ipynb
The most (no exaggeration) dangerous thing we can try here is to run a not trusted notebook. By default, running a not-trusted notebook leads to a
DeprecationWarning that stop it from running. However, if one insists to, we can pass
--allow-not-trusted flag to allow running.
runnb --allow-not-trusted not_trusted.ipynb
Deprecation message will be displayed but it would not block running. The executed not-trusted notebook could also be saved by using
--to. We will unsign the outcome of not-trusted notebook and mark it not trusted. However, the best practice is do not run not trusted notebooks. At least we should review the notebook first, and sign it trusted if it is safe. Make sure we understand what is happenning and what we are doing.
runnb(nb_path, allow_errors=False, no_stdio=False, to_file=None)
Run a notebook from current path.
str) - path to a notebook.
bool) - Wheither to allow error during single cell and continue running. When set to
True, the notebook will continue running following cells if error presents in some cell. Default
bool) - Wheither to stop recovering STDIO to default. When set to
True, default STDIO (usually command-line) will not be recovered. Results can be found only in the output notebook. Default
str) - Path to which file the executed notebook will be saved to. The notebook will not be save if set to
Noneor empty string. Default
DeprecationWarning- Raise if the notebook is not trusted and the warning is not filtered with
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.