jupytext

Jupytext: Write Jupyter Notebooks in pure Python

This skill helps users write Jupyter Notebooks using pure Python scripts, with the help of Jupytext to achieve .py ↔ .ipynb bidirectional conversion.

When to use this skill

Triggered when the user makes the following requests:

• Create a new Jupyter notebook
• Request to write a notebook in Python
• Mention jupytext, paired notebook, notebook version control
• Want to convert an existing notebook into a pure Python script
• Mention # %% cell separator (percent format)

Core workflow

Step 1: Confirm format preference

Must first ask the userwhich format they want:

Format	Use case
.py（percent format）	Needs version control, pure editor development, code review friendly
.ipynb	Needs native Jupyter experience, contains lots of outputs/charts

If the user only says "create a new notebook", by default recommend .py(percent format), because:

1. Git diff friendly, convenient for code review
2. Good editor support (VS Code, PyCharm, Spyder natively recognize # %%）
3. Can be read and edited without additional tools

Step 2: Generate the file

A. Create a .py percent format file

A complete percent format Python file looks like this:

# ---
# jupytext:
#   formats: ipynb,py:percent
#   notebook_metadata_filter: -all
# ---

# %% [markdown]
# # 标题
# 这是一段 Markdown 说明

# %% [markdown]
"""
也可以用三引号写多行 Markdown，
这在 Python 中更易读。
"""

# %%
import numpy as np
import pandas as pd

# %%
data = pd.DataFrame({
    "x": np.random.randn(100),
    "y": np.random.randn(100),
})
data.head()

Key syntax:

Syntax	Meaning
# %%	Code cell starts
# %% [markdown]	Markdown cell starts
# %% 标题文字 [markdown]	Markdown cell with title
# %% [markdown] + """..."""	Wrap multi-line Markdown with triple quotes (recommended)
# %% key="value"	With cell metadata

B. Create a .ipynb file

If the user chooses a traditional notebook, use nbformat or directly construct JSON. Refer to references/nbformat-guide.md to learn how to construct with Python .ipynb。

Step 3: Provide accompanying operations

Based on the user's needs, inform or execute:

1. Install Jupytext：pip install jupytext
2. Convert to notebook：jupytext --to notebook script.py
3. Bidirectional sync: first add YAML front matter at the top of the file declaring formats: ipynb,py:percent, then jupytext --sync script.py to sync both ends
4. Open .py as a notebook in JupyterLab: right-click → Open With → Notebook (requires the jupytext extension to be installed)

YAML Front Matter in detail

YAML front matter is a metadata block at the top of a .py file surrounded by # --- :

# ---
# jupytext:
#   formats: ipynb,py:percent
#   notebook_metadata_filter: -all
#   cell_metadata_filter: -all
# ---

# %% [markdown]
# # My Notebook

Common configurations:

Configuration	Effect
formats: ipynb,py:percent	Enable paired notebook (bidirectional update on save)
notebook_metadata_filter: -all	Do not output notebook-level metadata in the .py
cell_metadata_filter: -all	Do not output cell-level metadata in the .py
cell_markers: '"""'	Markdown cells use triple quotes instead of # comments

Configuration file

Create in the project root directory jupytext.toml to set global defaults:

# 所有 notebook 自动 paired
formats = "ipynb,py:percent"

# Markdown cell 用三引号
cell_markers = '"""'

or pyproject.toml：

[tool.jupytext]
formats = "ipynb,py:percent"
cell_markers = '"""'

Common CLI commands

# .py → .ipynb
jupytext --to notebook script.py

# .ipynb → .py (percent format)
jupytext --to py:percent notebook.ipynb

# 启用 paired notebook
jupytext --set-formats ipynb,py:percent notebook.ipynb

# 同步 paired notebook（以较新文件为准）
jupytext --sync notebook.ipynb

# 测试 round-trip 一致性
jupytext --test notebook.ipynb --to py:percent

# 用 black 格式化
jupytext --sync --pipe black notebook.ipynb

# 设置 kernel 信息
jupytext --set-kernel - notebook.py

light format supplement

In addition to percent format (# %%), Jupytext also supports light format, using # + / # - to mark cell boundaries:

# +
import numpy as np

# + [markdown]
# 这是一段说明

Since light format is less universal than percent format (only natively supported by Jupytext),it is generally not recommended, unless the user explicitly requests it.

Notes

1. Always ask the user which format they want first, do not make the decision for the user by default
2. .py Do not mix percent format and light format delimiters in a file
3. If the user already has a .ipynb file and wants version control, it is recommended to use jupytext --set-formats ipynb,py:percent to convert it to a paired notebook
4. The triple-quoted Markdown syntax is more readable, but it needs to be declared in the front matter or configuration cell_markers: '"""'
5. .py percent format files can be run directly in VS Code as Interactive Window cells without starting Jupyter

Reference resources

• Jupytext GitHub
• formats-scripts.md — detailed explanation of percent / light / sphinx formats
• paired-notebooks.md — paired notebook mechanism