Plain text notebooks on Renkulab with Jupytext

Did you ever struggle to read the git diff from a jupyter notebook?

Or maybe you committed a notebook with large outputs into your repository?

Although Jupyter notebooks are a great tool for prototyping and sharing code, the underlying file format can get in the way of collaborative work and version control.

The ipynb format contains rich metadata and combines code with its output. As a result, large chunks of the file are affected whenever a notebook cell is re-executed or the output changes slightly. When a version control system, such as git, tracks the notebook this results in large diffs obscuring important code changes.

With large outputs, such as complex figures, the notebook files can become very large and fill the commit history with irrelevant changes.

Fortunately, the jupytext package provides a solution to this problem ! This python package and jupyter plugin allow running text files as if they were notebooks. Furthermore, it supports multiple formats, including markdown documents and python scripts.

Try it!

You can try jupytext on Renku using our example repository

  1. Click launch - renku to start an interactive session
  2. Open text files as notebooks by double-clicking them, or right click > open as Notebook

To use jupytext in your own renku project, just add jupytext to requirements.txt. By default, you will need to right-click the files to open them as notebook. To make it the default behaviour when double clicking, you need to provide ~/.jupyter/labconfig/default_setting_overrides.json in the container. In our example repository, the config file is copied to the container using the Dockerfile.

4 Likes