朱皮文本

您是否一直希望 Jupyter 笔记本是纯文本文档？希望您可以在您最喜欢的 IDE 中编辑它们？在进行版本控制时获得清晰且有意义的差异？那么，Jupytext 很可能就是您正在寻找的工具！

文本笔记本

以py:percent格式编码的 Python 笔记本具有.py扩展名，如下所示：

 # %% [markdown]
# This is a markdown cell

# %%
def f(x):
  return 3*x+1

仅包含笔记本输入（以及可选的元数据）。文本笔记本非常适合版本控制。您还可以在 IDE 中编辑或重构它们 - 上面的.py笔记本是常规 Python 文件。

对于主要包含代码的笔记本，我们建议使用percent格式。 percent格式适用于 Julia、Python、R 和许多其他语言。

如果您的笔记本是面向文档的，则基于 Markdown 的格式（带有.md扩展名的文本笔记本）可能更合适。根据您计划使用笔记本做什么，您可能更喜欢 Myst Markdown 格式，它与 Jupyter Book、Quarto Markdown 甚至 Pandoc Markdown 具有良好的互操作性。

安装

在用于 Jupyter 的 Python 环境中安装 Jupytext。使用任一

 pip install jupytext

或者

 conda install jupytext -c conda-forge

然后，重新启动 Jupyter Lab 服务器，并确保在 Jupyter 中激活 Jupytext： .py和.md文件有一个笔记本图标，您可以在 Jupyter Lab 中右键单击将它们作为笔记本打开。

配对笔记本

具有.py或.md扩展名的文本笔记本非常适合版本控制。可以在 IDE 中方便地编辑或创作它们。您可以通过右键单击在 Jupyter Lab 中将它们作为笔记本打开并运行。但是，当笔记本关闭时，笔记本输出会丢失，因为只有笔记本输入保存在文本笔记本中。

文本笔记本的一个便捷替代方案是配对笔记本。这是一组两个文件，例如.ipynb和.py ，它们包含相同的笔记本，但格式不同。

您可以编辑配对笔记本的.py版本，然后通过选择从磁盘重新加载笔记本将编辑内容返回到 Jupyter 中。将从.ipynb文件（如果存在）重新加载输出。下次您在 Jupyter 中保存笔记本时， .ipynb版本将被更新或重新创建。

要在 Jupyter Lab 中配对笔记本，请使用命令面板中的命令Pair Notebook with percent Script配对：

要配对某个目录中的所有笔记本，请创建一个包含以下内容的配置文件：

 # jupytext.toml at the root of your notebook directory
formats = "ipynb,py:percent"

命令行

Jupytext 也可以在命令行中使用。你可以

将笔记本与jupytext --set-formats ipynb,py:percent notebook.ipynb
使用jupytext --sync notebook.py同步配对文件（输入从最近的配对文件加载）
使用jupytext --to ipynb notebook.py将一种格式的笔记本转换为另一种格式（如果需要特定的输出文件，请使用-o ）
使用例如jupytext --pipe black notebook.ipynb将笔记本通过管道连接到 linter

示例用例

版本控制下的笔记本

这是一个快速操作方法：

在 Jupyter 中打开.ipynb笔记本，并使用 Jupyter Lab 中的配对命令或全局配置文件将其与.py笔记本配对
保存笔记本 - 这将创建一个.py笔记本
将此.py笔记本添加到版本控制中

您可以从版本控制中排除.ipynb文件（除非您想查看输出版本！）。当用户打开并保存.py笔记本时，Jupytext 将在本地重新创建.ipynb文件。

使用 Git 在笔记本上进行协作

通过 Git 在 Jupyter 笔记本上进行协作变得与在文本文件上进行协作一样简单。

假设您的.py笔记本处于版本控制之下（见上文）。然后，

您的协作者提取.py笔记本
他们在 Jupyter 中将其作为笔记本打开（在 Jupyter Lab 中右键单击）
在那个阶段，笔记本没有输出。他们运行笔记本并保存它。重新生成输出，并创建本地.ipynb文件
他们编辑笔记本，并推送更新的notebook.py文件。该 diff 只不过是 Python 脚本上的标准 diff。
您提取更新的notebook.py脚本，然后刷新浏览器。输入单元格根据notebook.py的新内容进行更新。输出将从本地.ipynb文件重新加载。最后，内核变量保持不变，因此您可以选择仅运行修改后的单元格以获得新输出。

在 IDE 中编辑或重构笔记本

将笔记本与.py文件配对后，您可以在 IDE 中轻松编辑或重构笔记本的.py表示形式。

编辑完.py笔记本后，您只需在 Jupyter 中重新加载笔记本即可获取最新编辑内容。

注意：编辑配对的.py文件时，在 Jupyter 中关闭.ipynb笔记本会更简单。没有义务这样做；但是，如果不这样做，您应该准备好仔细阅读弹出消息。如果 Jupyter 尝试保存笔记本，而自上次重新加载以来配对的.py文件也在磁盘上进行了编辑，则会检测到冲突，并且系统会要求您决定笔记本的哪个版本（在内存中或在磁盘上）合适的一个。