All Collections
Literate Programming
Rendering Jupyter notebooks to HTML
Rendering Jupyter notebooks to HTML

How to execute notebooks reproducibly and save the output to the results folder

Shahar Zaks avatar
Written by Shahar Zaks
Updated over a week ago

While Jupyter notebooks are commonly used interactively, with cells executed individually, to publish on Code Ocean, we ask that notebooks be executed as a whole. This allows notebooks to serve as a reproducible record of the analysis from start to finish.

To do so, add commands* to your master script to execute jupyter nbconvert  with the --execute  flag listed. This renders the final results into /results as an HTML file.

jupyter nbconvert \
  --ExecutePreprocessor.allow_errors=True \
  --ExecutePreprocessor.timeout=-1 \
  --FilesWriter.build_directory=../results \
  --execute notebook.ipynb


  • The --ExecutePreprocessor.allow_errors=True flag isn't strictly necessary, but will reveal errors within the notebook, which makes debugging much easier.

  • The --ExecutePreprocessor.timeout=-1 flag will disable execution timeouts, allowing each cell to take as much time as it needs to execute.

  • If you are using Python 3 you may need to specify the following flag:

  • Code Ocean currently strips out the inline results from notebooks in the /code pane. This showcases that all notebooks in the /results  have been successfully rendered in the Code Ocean environment.

  • See nbconvert's excellent documentation for more details

*These commands can also be used to render a Jupyter notebook directly from the command line.

Did this answer your question?