Notebook Execution
run
executes all codes cells in the notebook, from first to last,
comparable to Kernel > Restart & Run All
in the Jupyter Notebook Editor.
Each cell is executed separately,
in the context of the global state,
which is empty at the start and updated as cells execute.
Unless in quiet mode,
run
will report some execution statistics on stdout
:
number of code cells
number of executed code cells
number of executions that resulted in an error
Result File Name
The result of running notebook nb.ipynb
is written to nb-run.ipynb
,
unless the option --inplace
is applied.
The result name addition can be adjusted in the configuration file
by setting run_result_name
;
see Configuration Files.
Options
The following options are supported by run
:
-e, --allow-errors, -E, --no-allow-errors
continue on errors (default: True)
-b, --clean-before, -B, --no-clean-before
clean code output before running (default: True
-a, --clean-after, -A, --no-clean-after
clean code metadata after running (default: True)
-k KERNEL_NAME, --kernel-name KERNEL_NAME
name of kernel to use, e.g. python3; for kernel
specified in notebook; default: '')
-p RUN_PATH, --run-path RUN_PATH
working directory for execution ;"" for current
working directory (default: '')
-t TIMEOUT, --timeout TIMEOUT
timeout time in seconds per cell; -1 for unlimited
(default: -1)
-i, --interrupt-on-timeout, -I, --no-interrupt-on-timeout
interrupt execution on timeout (default: False)
-r, --record-timing, -R, --no-record-timing
record execution times (default: True)
-w, --append-cell, -W, --no-append-cell
append special code cell (default: '# Automatically
added code cell: lists all global names defined by
this notebook.\n%whos') before executing notebooks
(default: False)
--streams-head STREAMS_HEAD
limit output streams to a maximum number of lines per
cell; -1 for unlimited (default: 1000)
Dry Run
By default,
the result of executing notebook nb.ipynb
is written to nb-run.ipynb
,
unless the dry-run
option is in effect.
The dry-run
option suppresses writing of the resulting notebook.
It does not suppress execution.
Allow Errors
By default, run
executes all code cells, even when errors occur.
Such errors typically give rise to an error
element among the cell outputs in the notebook
(which the Jupyter Notebook Editor shows on a red background).
The no-allow-errors
option makes run
abort execution at the first error.
Error details are then reported on stderr
.
Timeout
By default, run
does not limit the execution time.
The timeout
option sets a limit in seconds on the execution time per cell.
Use -1
as value to remove the limit.
Interrupt on Timeout
By default, run
interrupts the kernel with a KeyboardInterrupt
when a timeout occurs
(which does not stop further execution when allowing errors).
When not interrupting on timeout,
run
aborts execution with a CellTimeoutError
when a timeout occurs
(which stops further execution even when allowing errors).
Record Timing
By default, run
records cell execution times in the resulting cell metadata under the key execution
.
See nbformat, Cell metadata
for details.
Kernel Name
By default, run
uses the kernel associated with the notebook
(as specified in its metadata > kernel
attribute).
The kernel_name
option overrides this default behavior and sets a specific kernel.
Typical choices are
python2
python3
Run Path
By default, the notebook is executed in the current working directory
where the tool was invoked.
The run-path
option sets a specific path to be the working directory.
Clean Before
By default, run
cleans the notebook before execution:
the outputs of all code cells are removed,
their execution counts are cleared, and
ExecuteTime
andexecution
metadata is removed.
This ensures that the the notebook is run in a clean environment. In particular, when executing until the first error, no spurious outputs and metadata from a previous run will be left in the notebook.
The not-before
option suppresses this pre-cleaning step.
Clean After
By default, run
cleans the notebook after execution:
the
collapased
andscrolled
metadata are removed from all code cells
Currently, it appears that execution through nbconvert
will make all output cells collapsed and scrolled.
When such a notebook is subsequently opened in the Jupyter Notebook Editor,
no outputs will be visible, until they are actively opened by the user
(either by clicking to the left of the output area of a cell,
or through the Cell
menu to toggle the output cell state.
The not-after
option suppresses this post-cleaning step.
Append Cell
The append-cell
option appends to the notebook (before execution) a code cell containing:
# Automatically added code cell: lists all global names defined by this notebook.
%whos
This will show an overview of all names defined a the global level of the notebook, their types, and some data/info. Also see the example below.
The content of the appended code cell can be changed in a configuration file.
Using the cat
tool, you can prepend and append entire notebooks.
Streams Head
The streams-head
option will limit the amount of data in output streams
(both stdout and stderr) that is written to the resulting notebook,
by showing only the head.
The number of lines to show is a parameter to this option (use -1 for unlimited output).
It applies per cell.
This option serves as a protection to generate excessively large notebooks, when the input notebook contains ‘overzealous’ code. An example of ‘overzealous’ code is an infinite loop that contains a call to print.
JSON Output
See Write JSON Output for general information about JSON output.
run
produces the following members in the JSON output:
Name
Value
"code cells"
count of code cells
"executed"
count of executed code cells
"with errors"
count of executed code cells with errors
Note that members are absent when count is zero.
Examples
Example output when running a single notebook without options:
$ nbtb run test.ipynb
Execution statistics:
12 code cells
12 executed
2 with errors
The execution result is written to test-run.ipynb
.
Example output when running to first error in verbose mode without writing the result:
$ nbtb run -E tool-faq.ipynb test.ipynb -v -n
Dry run (no files written)
Options for nbrun:
Cleaning code output and ['ExecuteTime', 'execution'] metadata before running
Timeout: unlimited
Kernel name: from notebook
Working dir: current directory
Stopping at first error
Cell execution does not time out
Recording execution times
Not appending code cell with %whos
Cleaning ['collapsed', 'scrolled'] code metadata after running
Not limiting output streams
::::::::::::::
short.ipynb
::::::::::::::
Execution statistics:
1 code cells
0 code cells with empty source
1 executed
0 with errors
No file written
::::::::::::::
test.ipynb
::::::::::::::
Notebooks processed: 1
Processing of "test.ipynb" failed (CellExecutionError): An error occurred while executing the following cell:
------------------
# NameError
undefined
------------------
NameError: name 'undefined' is not defined
Tool 'run' aborted.
Here is an example with the append-cell
(-w
) option.
The execution result is written to test-run.ipynb
.
Next, we use nbshow
to inspect the output of the last cell
(Note that nbshow
is part of the nbdime
package;
see documentation of nbdime
.)
$ nbtb run -w test.ipynb
Execution statistics:
13 code cells
0 code cells with empty source
13 executed
2 with errors
$ nbshow test-run.ipynb | tail -n -16
code cell 19:
execution_count: 13
source:
# Automatically added code cell: lists all global names defined by this notebook.
%whos
outputs:
output 0:
output_type: stream
name: stdout
text:
Variable Type Data/Info
---------------------------------
df DataFrame 0\n0 3\n1 1\n2 4\n3 1\n4 5\n5 9
i int 99
pd module <module 'pandas' from '/o<...>ages/pandas/__init__.py'>
sys module <module 'sys' (built-in)>