This page was generated from docs/source/getting_started.Rmd, with configuration: sphinx_ipypublish_all.ext

1. Getting Started

1.1. IPyPublish Basics

This document is written in a Jupyter Notebook (or more precisely an RMarkdown version of the notebook), which is executed and converted auto-magically to the page you are reading. This is the power of IPyPublish!

print("Hallo everybody!")
Hallo everybody!

When analysing data with Python and Jupyter Notebooks, there are three ‘modes’ we will be switching between:

  • Writing and running analysis code (i.e. populating code cells)

  • Documenting our analysis (i.e. populating markdown cells)

  • Marking up and converting our notebooks to a distributable format

IPyPublish, in conjunction with some other great packages, provides enhancements for working in each of these modes and the means to seamlessly switch between them:

  1. Writing Code and Formatting Output

  2. Writing Markdown

  3. Notebook Conversion

1.2. Installation

Using Conda is recommended for package management, in order to create self contained environments with specific versions of packages. The main external packages required are the Jupyter notebook and Pandoc (for markdown conversion):

$ conda create --name ipyreport -c conda-forge jupyter pandoc==2.6
$ source activate ipyreport

New in version 0.9.3: ipypublish is now available on Conda (recommended):

$ conda install -c conda-forge ipypublish

ipypublish can also be pip installed into this environment:

$ pip install ipypublish

optionally, to include install dependencies for sphinx exporters:

$ pip install ipypublish[sphinx]

For converting to PDF, the TeX document preparation ecosystem is required, in particular latexmk), which can be installed from:

For helpful extensions to the notebooks core capabilities, see the Jupyter Notebook Extensions package:

$ conda install --name ipyreport jupyter_contrib_nbextensions

Additionally, a more extensive setup of useful packages (used to create the examples) are provided by the anaconda distribution which can be installed in to a new environment

$ conda create --name ipyreport anaconda

1.3. Basic Conversion

The nbpublish script provides terminal access to the notebook conversion application. To see all the options:

$ nbpublish --help

To see all the conversion configurations:

$ nbpublish -le

or to see a subset of configurations with a verbose description, use a regex:

$ nbpublish -le *latex* -lv

To run a basic conversion to PDF and auto-load it in a web browser

$ nbpublish -pdf -lb -f latex_ipypublish_nocode path/to/notebook.ipynb

For a more detailed explanation see the Notebook Conversion section.


The default conversion (latex_ipypublish_main) will NOToutput any cells that are not tagged with metadata. To output all notebook content by default, use _ipypublish_all.


For existing notebooks: the nb_ipypublish_all and nb_ipypublish_nocode converters (see below) can be helpful for outputting a notebook, with identical content to that input, but with default metatags defining how content is to be output.

The nbpresent script additionally handles serving reveal.js slides to a webbrowser.

$ nbpresent -h
$ nbpresent -f slides_ipypublish_nocode path/to/notebook.ipynb


For offline use, simply download the latest version of reveal.js here, rename the entire folder to reveal.js and place it in the same folder as the converted .slides.html file. The slides can also be saved to PDF by appending pdf-export to the url (see here for details).

1.4. Troubleshooting

For installation issues, GitHub Actions is used to automatically test updates against multiple Python versions, for Linux, Windows and OSX, Therefore, to troubleshoot any installation/run issues, it is best to first look at the test workflow and test runs for working configurations.

The requirements-lock.txt file can also be used to provide exact versions of working package dependencies.

For conversion issues, for both nbpublish and nbpresent, detailed log messages of the run are output to both the console and file (default path: converted/notebook_name.nbpub.log). Try running with options:

$ nbpublish --log-level debug --print-traceback notebook.ipynb

To debug PDF conversions, use the --pdf-debug flag. If there is still an error, please raise an issue on the GitHub repository, including the run environment and the log file.