Jupytext：让 Jupyter Notebook 变成纯文本

Jupytext：让 Jupyter Notebook 变成纯文本

Jupytext 在 GitHub 上已经拿到 7,179 Star 了。

这个工具只做一件事：把 Jupyter Notebook 转换成纯文本格式，同时保留双向同步能力。你可以在 IDE 里写代码、用 Git 做版本控制，随时还能回到 Jupyter 里运行。

1、这工具解决什么问题

用过 Jupyter Notebook 的人都遇到过这几个麻烦。

diff 看不懂。Notebook 是 JSON 格式，每次改动产生的 diff 都是大段元数据混杂代码，Review 起来很费劲。想在 Git 里追溯某一行代码是什么时候改的，几乎做不到。

IDE 不支持。Notebook 只能在 Jupyter 环境里编辑，想用自己的 IDE 做重构、跳转定义、批量替换，都不方便。

版本控制混乱。团队成员各自改一个 .ipynb 文件，合并冲突时基本只能靠人工比对。

Jupytext 把这些问题全解决了。它让 Notebook 以纯文本形式存在，同时和 .ipynb 保持同步。

2、文本格式的 Notebook 长什么样

Jupytext 支持几种纯文本格式，最常用的是py:percent和 Markdown。

py:percent格式就是一个普通的 .py 文件，用# %%标记单元格边界：

# %% [markdown]# 这是一个 markdown 单元格# %%deff(x):return3*x+1

这种文件在 IDE 里就是标准 Python 脚本，可以正常编辑、运行、调试。Git diff 也变成了一目了然的代码变更。

如果你的 Notebook 偏文档性质，也可以转成 .md 格式，支持 Myst Markdown、Quarto Markdown 等多种变体。

3、Paired Notebooks 怎么用

只存纯文本有个问题：输出结果丢了。Notebook 里的图表、运行结果在文本格式里是不保存的。

Jupytext 的解决方案是 Paired Notebooks。同一个 Notebook 同时保存两份文件：一份 .ipynb 保留输出，一份 .py 或 .md 供编辑和版本控制。

两份文件自动同步。你在 IDE 里改了 .py 文件，回到 Jupyter 点一下 reload，改动就生效了。在 Jupyter 里运行并保存，.py 文件也会更新。

开启配对很简单，在 JupyterLab 的 Command Palette 里选 “Pair Notebook with percent Script” 就行。也可以写一个配置文件：

# jupytext.toml formats = "ipynb,py:percent"

4、命令行也能用

Jupytext 提供了完整的命令行接口：

# 给已有 notebook 设置配对jupytext --set-formats ipynb,py:percent notebook.ipynb# 同步配对文件jupytext--syncnotebook.py# 格式转换jupytext--toipynb notebook.py# 把 notebook 灌给 linterjupytext--pipeblack notebook.ipynb

这些操作都可以集成到 CI 流程或者 Makefile 里。

5、适合哪些人

• 用 Git 管理 Notebook 的团队开发者
• 习惯在 IDE 里写代码、偶尔需要 Jupyter 交互式调试的人
• 需要把 Notebook 转成脚本部署到生产环境的人

Jupytext 的安装很常规，pip 或 conda 都可以：

pipinstalljupytext

装完重启 JupyterLab，.py 和 .md 文件就会显示 Notebook 图标，右键即可当作 Notebook 打开。

install jupytext

装完重启 JupyterLab，.py 和 .md 文件就会显示 Notebook 图标，右键即可当作 Notebook 打开。