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 and execution 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 and scrolled 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)>