Package: jupytext
JupytextHave 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!Text NotebooksA Python notebook encoded in thepy:percentformathas a.pyextension and looks like this:# %% [markdown]
# This is a markdown cell

# %%
def f(x):
  return 3*x+1Only the notebook inputs (and optionally, the metadata) are included. Text notebooks are well suited for version control. You can also edit or refactor them in an IDE - the.pynotebook above is a regular Python file.We recommend thepercentformat for notebooks that mostly contain code. Thepercentformat is available for Julia, Python, R and many otherlanguages.If your notebook is documentation-oriented, aMarkdown-based format(text notebooks with a.mdextension) might be more appropriate. Depending on what you plan to do with your notebook, you might prefer the Myst Markdown format, which interoperates very well with Jupyter Book, or Quarto Markdown, or even Pandoc Markdown.InstallationInstall Jupytext in the Python environment that you use for Jupyter. Use eitherpip install jupytextorconda install jupytext -c conda-forgeThen, restart your Jupyter Lab server, and make sure Jupytext is activated in Jupyter:.pyand.mdfiles have a Notebook icon, and you can open them as Notebooks with a right click in Jupyter Lab.Paired NotebooksText notebooks with a.pyor.mdextension are well suited for version control. They can be edited or authored conveniently in an IDE. You can open and run them as notebooks in Jupyter Lab with a right click. However, the notebook outputs are lost when the notebook is closed, as only the notebook inputs are saved in text notebooks.A convenient alternative to text notebooks arepaired notebooks. These are a set of two files, say.ipynband.py, that contain the same notebook, but in different formats.You can edit the.pyversion of the paired notebook, and get the edits back in Jupyter by selectingreload notebook from disk. The outputs will be reloaded from the.ipynbfile, if it exists. The.ipynbversion will be updated or recreated the next time you save the notebook in Jupyter.To pair a notebook in Jupyter Lab, use the commandPair Notebook with percent Scriptfrom the Command Palette:To pair all the notebooks in a certain directory, create aconfiguration filewith this content:# jupytext.toml at the root of your notebook directory
formats = "ipynb,py:percent"Command lineJupytext is also available at thecommand line. You canpair a notebook withjupytext --set-formats ipynb,py:percent notebook.ipynbsynchronize the paired files withjupytext --sync notebook.py(the inputs are loaded from the most recent paired file)convert a notebook in one format to another withjupytext --to ipynb notebook.py(use-oif you want a specific output file)pipe a notebook to a linter with e.g.jupytext --pipe black notebook.ipynbSample use casesNotebooks under version controlThis is a quick how-to:Open your.ipynbnotebook in Jupyter andpairit to a.pynotebook, using either thepaircommand in Jupyter Lab, or a globalconfiguration fileSave the notebook - this creates a.pynotebookAdd this.pynotebook to version controlYou might exclude.ipynbfiles from version control (unless you want to see the outputs versioned!). Jupytext will recreate the.ipynbfiles locally when the users open and save the.pynotebooks.Collaborating on notebooks with GitCollaborating on Jupyter notebooks through Git becomes as easy as collaborating on text files.Assume that you have your.pynotebooks under version control (see above). Then,Your collaborator pulls the.pynotebookThey open itas a notebookin Jupyter (right-click in Jupyter Lab)At that stage the notebook has no outputs. They run the notebook and save it. Outputs are regenerated, and a local.ipynbfile is createdThey edit the notebook, and push the updatednotebook.pyfile. The diff is nothing else than a standard diff on a Python script.You pull the updatednotebook.pyscript, and refresh your browser. The input cells are updated based on the new content ofnotebook.py. The outputs are reloaded from your local.ipynbfile. Finally, the kernel variables are untouched, so you have the option to run only the modified cells to get the new outputs.Editing or refactoring a notebook in an IDEOnce your notebook ispairedwith a.pyfile, you can easily edit or refactor the.pyrepresentation of the notebook in an IDE.Once you are done editing the.pynotebook, you will just have toreloadthe notebook in Jupyter to get the latest edits there.Note: It is simpler to close the.ipynbnotebook in Jupyter when you edit the paired.pyfile. There is no obligation to do so; however, if you don't, you should be prepared to read carefully the pop-up messages. If Jupyter tries to save the notebook while the paired.pyfile has also been edited on disk since the last reload, a conflict will be detected and you will be asked to decide which version of the notebook (in memory or on disk) is the appropriate one.More resourcesRead more about Jupytext in thedocumentation.If you're new to Jupytext, you may want to start with theFAQor with theTutorials.There is also this short introduction to Jupytext:.