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.

Files for rst2ipynb, version 0.2.3
Filename, size File type Python version Upload date Hashes
Filename, size rst2ipynb-0.2.3-py3-none-any.whl (7.1 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size rst2ipynb-0.2.3.tar.gz (6.1 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page