Skip to main content

A reST to Jupyter notebook converter

Project description

This project provides a way to convert standalone reStructuredText files to Jupyter notebook files.

This is currently achieved by converting to markdown using pandoc and then to a Jupyter notebook using notedown, plus some configuration and tweaks.


Python 3 (for proper UTF-8 support in notedown), pandoc, notedown


Install pandoc and then this module as usual:

git clone
cd rst-to-ipynb
pip3 install .

pip3 will install the other dependencies as needed.

Caveat: the notedown package on pipy (1.5.0, 2015-10-07) is somewhat outdated; for better conversion, it is recommended to install the latest version from the github repo.


To convert a reST file xxx.rst to a Jupyter notebook xxx.ipynb, run:

rst2ipynb xxx.rst -o xxx.ipynb



  • [X] Handle Sage’s doctests

  • [X] Fenced code blocks: fix incompatibility between pandoc output and notedown input.

    Fixed in notedown; see:

  • [ ] Configurability of the default ReST role, in particular to handle maths in Sage’s ReST dialect.

    Current status: hardcoded for Sage.

  • [ ] Configurability of custom ReST roles, in particular to handle Sage’s custom roles

  • [ ] Proper argument parsing; escape characters, spaces, … are not

    yet supported

  • [ ] Handle input/output blocks within itemize and other indented constructions


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rst2ipynb-0.2.3.tar.gz (6.1 kB view hashes)

Uploaded Source

Built Distribution

rst2ipynb-0.2.3-py3-none-any.whl (7.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page