Package: jupyter-runner
Welcome to Jupyter-Runner’s documentationJupyter runners allows to runmultiple notebooksovermultiple sets of parameters.Notebook execution can happen in parallel with a fixed number of workers.Installationpip install jupyter-runnerUsagejupyter-runner [options] <notebook>...

    --parameter-file=<PARAMETER_FILE>**    Optional parameters files containing one parameter instance by line, setting the environment.
    Example with 2 sets of 3 parameters:
        VAR1=VAL1 VAR2=VAL2 VAR3=VAL3
        VAR1=VAL5 VAR2=VAL18 VAR3=VAL42
    --workers=<workers>                    Maximum number of parallel execution [Default: 1]
    --output-directory=<OUTPUT_DIRECTORY>  Output directory [Default: .]
    --overwrite                            Overwrite output files if they already exist.
    --format=<FORMAT>                      Output format: html, notebook... [Default: html]
    --debug                                Enable debug logs
    --help                                 Display this help
    --version                              Display version
    --timeout=<TIMEOUT>                    Cell execution timeout in seconds.  [Default: -1]
    --allow-errors                         Allow errors during notebook execution.TutorialRun a simple notebookjupyter-runner notebook.ipynbBy default, the process creates output filenotebook.htmlin current directory.Run multiple notebooksjupyter-runner notebookA.ipynb notebookB.ipynbBy default, the process creates output filesnotebookA.htmlandnotebookB.htmlin current directory.Run notebook with parametersUse environment variables on command-line.ENV_VAR=xxx jupyter-runner notebook.ipynbIn python notebook, variables can be retrieved usingos.environ:importosenv_var=os.environ.get('ENV_VAR','a_default_value')# usage of env_var in your codeBy default, the process creates output filenotebook.htmlin current directory.
The notebook variables passed by the user can impact the rendering of the output.Run notebook with multiple sets of parametersCreate a file with multiple set of parameters, one set of parameters per line.Example file containing 2 sets of 3 parameters:VAR1=VAL1 VAR2=VAL2 VAR3=VAL3
VAR1=VAL5 VAR2=VAL18 VAR3='VAL42 with space'Then run jupyter-runner specifying the path tomy_parameter_filejust created:jupyter-runner --parameter-file=my_parameter_file notebook.ipynbBy default, the process creates output filesnotebook_1.htmlandnotebook_2.htmlin current directory.Run multiple notebooks with multiple sets of parametersjupyter-runner can combine multiple set of parameters on multiple notebooks.
When there areNsets of parameters running onMnotebooks, there will beNxMdistinct output files.jupyter-runner --parameter-file=my_parameter_file notebookA.ipynb notebookB.ipynbBy default, the process creates output filesnotebookA_1.html,notebookA_2.html,notebookB_1.html,notebookB_2.htmlin current directory.Change output directoryjupyter-runner --output-directory results notebook.ipynbThe process create output fileresults/notebook.html`. ``resultsdirectory is created if it does not pre-exist.Use S3 inputs/outputsjupyter-runner --output-directory=s3://bucket/results/ s3://bucket/notebooks/notebook.ipynbThe process create output files3://bucket/results/notebook.htmlbased on a notebook stored from S3.Files are downloaded to a local temporary only available to the current user and removed at the end or in case of exceptions.Overwrite existing outputsBy default, jupyter-runner skip the run when output file(s) already exists.
To overwrite the files, use the--overwriteoption:jupyter-runner --overwrite notebook.ipynbUse multiple workersBy default, only 1 notebook will be executed at the same time.
Use--workersoption to specify the number of notebooks to run in parallel.jupyter-runner --workers 3 --parameter-file=my_parameter_file notebookA.ipynb notebookB.ipynbThe above command will start to run 3 notebook output over the 4 requested. When the first execution finishes, the 4th notebook is launched and so on.Change output typeList of possible output types are available here:https://nbconvert.readthedocs.io/en/latest/usage.html#default-output-format-htmljupyter-runner --format notebook --output-directory results notebook.ipynbReport mode (hide input)jupyter-runner --hide-input notebook.ipynbThe process create output filenotebook.htmlwithout any input cells.
Markdown and output cells are kept, but input code cells do not show.
This feature is handy to create user-friendly reports.Change output file suffixWhen multiple notebooks are run with a list of parameters, output filenames are suffixed by_1,_2, …
This default can be overriden by setting parameter JUPYTER_OUTPUT_SUFFIX in parameter set.Examplemy_parameter_file:VAR1=VAL1 VAR2=VAL2 VAR3=VAL3 JUPYTER_OUTPUT_SUFFIX=AAA
VAR1=VAL5 VAR2=VAL18 VAR3='VAL42 with space' JUPYTER_OUTPUT_SUFFIX=BBBjupyter-runner --parameter-file=my_parameter_file notebook.ipynbThis run will generate two files:notebook_AAA.htmlandnotebook_BBB.htmlChange cell execution timeoutBy default, timeout is set to -1, meaning infinite.
It is possible to set the cell execution timeout (in seconds) with--timeoutjupyter-runner --timeout 60 notebook.ipynbAllow error in notebook executionBy default, errors in notebook execution stops its execution and return an error code.
Setting--allow-errorsoption allows to ignore the error and continue the execution, returning a valid code.jupyter-runner --allow-errors notebook.ipynbSend e-mail containing outputYou can send an e-mail containing attachments using--mail-tooption.
Other mail options available (subject, from, cc, bcc…) as well as attaching
each output in separate file or regrouped together within a LZMA compressed
zip (default).jupyter-runner notebook.ipynb --mail-to=me@example.com