朱皮文本

您是否一直希望 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檔案也在磁碟上進行了編輯，則會偵測到衝突，並且系統會要求您決定筆記本的哪個版本（在記憶體中或在磁碟上）合適的一個。