jupytext
Have you always wished Jupyter notebooks were plain text documents? Wished you could edit them in your favorite IDE? And get clear and meaningful diffs when doing version control? Then... Jupytext may well be the tool you're looking for!
Jupytext is a plugin for Jupyter that can save Jupyter notebooks as either
- Markdown files (or MyST Markdown files, or R Markdown documents)
- Scripts in many languages.
Use cases
Common use cases for Jupytext are:
- Doing version control on Jupyter Notebooks
- Editing, merging or refactoring notebooks in your favorite text editor
- Applying Q&A checks on notebooks.
Install
You can install Jupytext with
pip install jupytext- or
conda install jupytext -c conda-forge.
Please note that Jupytext includes an extension for Jupyter Lab. In the latest version of Jupytext, this extension is compatible with Jupyter Lab >= 3.0 only. If you use Jupyter Lab 2.x, please either stay with Jupytext 1.8.2, or install, on top of the latest pip or conda version of Jupytext, a version of the extension that is compatible with Jupyter Lab 2.x:
jupyter labextension install [email protected] # For Jupyter Lab 2.x
Then, restart your Jupyter server (for more installation details, see the install section in the documentation).
When Jupytext is installed, .py and .md files have a notebook icon. And you can really open and run these files as notebooks
With a click on the text file in Jupyter Notebook
(click on the image above to try this on 
)
With a right click and open with notebook in Jupyter Lab
(click on the image above to try this on )
Paired notebooks
The most convenient way to use Jupytext is probably through paired notebooks.
To pair a given .ipynb or text notebook to an additional notebook format, use either
the "pair notebook with..." commands in Jupyter Lab
the "pair notebook with..." menu entries in Jupyter Notebook
jupytext at the command line
with e.g.
jupytext --set-formats ipynb,py:percent notebook.ipynb
see the documentation.
or a local or global jupytext.toml configuration file.
with e.g. the following content:
formats = "ipynb,py:percent"
see the documentation.
When you save a paired notebook in Jupyter, both the .ipynb file and the text version are updated on disk.
When a paired notebook is opened or reloaded in Jupyter, the input cells are loaded from the text file, and combined with the output cells from the .ipynb file.
You can edit the text representation of the notebook in your favorite editor, and get the changes back in Jupyter by simply reloading the notebook (Ctrl+R in Jupyter Notebook, "reload notebook" in Jupyter Lab). And the changes are propagated to the .ipynb file when you save the notebook.
Alternatively, you can synchronise the two representations by running jupytext --sync notebook.ipynb at the command line.
