Jupytext — Jupyter Notebooks as Plain Text Files

Introduction

Jupytext is a plugin for Jupyter that allows notebooks to be saved as plain-text documents: Python scripts, Markdown files, R Markdown, or Julia scripts. This solves the long-standing pain of version-controlling Jupyter notebooks, which store cell outputs as large JSON blobs that produce unreadable diffs. With Jupytext, the text representation is always in sync with the notebook, making git diffs clean and code reviews practical.

What Jupytext Does

• Converts Jupyter notebooks to and from Python scripts, Markdown, R Markdown, and other text formats
• Pairs notebooks with text files so both stay synchronized automatically on save
• Enables meaningful git diffs by storing code and markdown in plain text
• Allows editing notebook content in any IDE or text editor with round-trip fidelity
• Supports the percent format, light format, Sphinx-gallery, and Markdown with code fences

Architecture Overview

Jupytext registers as a Jupyter contents manager that intercepts notebook save and load operations. When a notebook is paired with a text format, saving the .ipynb also writes the .py (or .md) file, and vice versa. The conversion engine parses notebook JSON and maps cells to text regions using format-specific markers (e.g., # %% for the percent format). Cell metadata and outputs are preserved in the .ipynb while the text file stays clean.

Self-Hosting & Configuration

• Install via pip: pip install jupytext or conda: conda install -c conda-forge jupytext
• Jupytext integrates automatically with JupyterLab and classic Jupyter Notebook
• Configure default formats in jupytext.toml or pyproject.toml at the project root
• Set notebook metadata to pair formats: jupytext --set-formats ipynb,py:percent
• Use pre-commit hooks to ensure text representations stay in sync

Key Features

• Two-way sync: edit the .py file in VS Code, open the .ipynb in Jupyter, and both reflect changes
• Multiple text formats: percent scripts (# %%), light scripts, Markdown, R Markdown, and Quarto
• Clean git diffs: text files produce line-by-line diffs instead of JSON blob changes
• CI/CD integration: run notebooks as scripts in pipelines without Jupyter
• Pre-commit hooks: automatically update paired files before commits

Comparison with Similar Tools

• nbconvert — One-way export from notebooks; Jupytext provides two-way sync with live pairing
• nbstripout — Strips outputs from .ipynb for cleaner commits; Jupytext eliminates the JSON problem entirely
• Papermill — Parameterizes and executes notebooks; Jupytext focuses on representation, not execution
• Quarto — Publishing system with notebook support; Jupytext is format-agnostic and lighter weight
• VS Code Notebook API — Renders notebooks in VS Code; Jupytext lets you edit notebook content as a plain file

FAQ

Q: Do I lose cell outputs when converting to a text format? A: The text file does not store outputs. If you pair the notebook (.ipynb + .py), the .ipynb retains outputs while the .py stays clean. Reopening the .py in Jupyter creates a notebook without outputs.

Q: Can I use Jupytext with JupyterLab? A: Yes. Jupytext integrates with JupyterLab via a contents manager extension. After installation, you can open .py and .md files as notebooks directly.

Q: Does Jupytext work with VS Code? A: Yes. Edit the .py file in VS Code, and the paired .ipynb updates on the next save in Jupyter. Some VS Code extensions also support Jupytext natively.

Q: How do I set up Jupytext for a team project? A: Add a jupytext.toml with default formats at the repo root. Add a pre-commit hook to keep text files in sync. Commit the .py files and optionally the .ipynb files.

Sources

• https://github.com/mwouts/jupytext
• https://jupytext.readthedocs.io/