🔍
Clean, reviewable diffs
No more unreadable JSON blobs. Text notebooks produce line-by-line diffs you can actually review in a pull request.
Jupytext saves your notebooks as .py or .md files — easy to edit
in any IDE, friendly to version control, and trivial for AI assistants to read and refactor.
# %% [markdown]
# # Sales report
- df = df.dropna()
+ df = df.dropna().reset_index(drop=True)
+ df["margin"] = df.revenue - df.cost
# %%
df.groupby("region").margin.sum().plot.bar()The same notebook — as a diff your team can actually read.
A one-line code change comes with execution counts, base64 image outputs, and cell metadata in the diff. Jupytext gives you a text file that contains only the source — the part you actually write and review.
notebook.ipynb- "execution_count": 12,
- "outputs": [{"data": {"image/png":
- "iVBORw0KGgoAAAANSUhEUg..."}}],
- "metadata": {"id": "a1b2c3"},
- "source": ["df = df.dropna()"]
+ "execution_count": 47,
+ "outputs": [{"data": {"image/png":
+ "iVBORw0KGgoAAAANSUhEUg..."}}],notebook.py # %%
- df = df.dropna()
+ df = df.dropna().reset_index(drop=True)
Keep the interactive notebook you love. Gain everything that plain text gives you.
No more unreadable JSON blobs. Text notebooks produce line-by-line diffs you can actually review in a pull request.
Open your notebooks in VS Code, PyCharm, Spyder, vim — anywhere. No JSON, no merge nightmares, full editor superpowers.
Run black, ruff, isort or flake8 over your notebooks like ordinary scripts. Pipe them through any tool from the CLI.
A text notebook is a valid module. Import functions from it, or run it as a script — no copy-paste between files.
Pair the text file with an .ipynb and keep your rich outputs. Inputs come from the text, outputs from the notebook.
Python, R, Julia and more — as percent scripts, Markdown, MyST, Quarto or Pandoc. Pick what fits each notebook.
Coding assistants like Claude, GitHub Copilot and Cursor work in plain text. Pair your notebooks with Jupytext and they can read, edit and refactor them directly — no JSON wrangling, no broken outputs, no special tooling.
# %% [markdown]
# ### Refactor: vectorize the loop 🤖
- totals = []
- for r in regions:
- totals.append(df[df.region==r].sales.sum())
+ totals = df.groupby("region").sales.sum()
Keep a rich .ipynb (with outputs) alongside a clean .py or
.md. Jupytext keeps them in sync — commit only the text file.
Tell Jupytext to pair your notebook with a text format — once, or for the whole project via jupytext.toml.
Edit the .py in your IDE or with an AI assistant, or run the notebook in Jupyter. Reload to pick up changes.
On save (or with jupytext --sync) both files update. Version-control the text; outputs stay in the .ipynb.
jupytext --to py:percent notebook.ipynbjupytext --set-formats ipynb,py:percent notebook.ipynbjupytext --sync notebook.ipynbjupytext --pipe black notebook.ipynb# jupytext.toml
formats = "ipynb,py:percent"The cell below is the same content in each format. Pick whichever suits the notebook.
# %% [markdown]
# # Analysis
# A quick look at the data.
# %%
import pandas as pd
df = pd.read_csv("data.csv")
df.describe()Best for code-heavy notebooks — cell markers understood by VS Code, PyCharm, Spyder & Hydrogen.
# # Analysis
# A quick look at the data.
import pandas as pd
df = pd.read_csv("data.csv")
df.describe()Best when you want a script that barely looks like a notebook — minimal cell markers.
# Analysis
A quick look at the data.
```python
import pandas as pd
df = pd.read_csv("data.csv")
df.describe()
```Best for documentation-first notebooks — code lives in fenced blocks.
# Analysis
A quick look at the data.
```{code-cell} ipython3
import pandas as pd
df = pd.read_csv("data.csv")
df.describe()
```Best for rich technical docs & Jupyter Book — directives, cross-refs and more.
---
title: Analysis
---
A quick look at the data.
```{python}
import pandas as pd
df = pd.read_csv("data.csv")
df.describe()
```Best for publishing — pairs with the Quarto scientific publishing system.
Install Jupytext, pair a notebook, and enjoy reviewable diffs, IDE editing and AI-ready files.