🎉

Jupyter NotebookをGitで管理する方法

に公開
Git
Python
jupyter
tech

はじめに

Gitを練習していた際に、「Jupyter NotebookとGitって相性が悪いのでは？」と疑問に思い、調べてみました。
本記事では、Jupyter NotebookをGitで管理する際の問題点と、それを解決する方法について紹介します。

結論

Jupyter Notebook (.ipynb) はGitとの相性が悪いですが、解決策として以下の方法が挙げられます。

  1. .ipynb をGitで管理するなら nbstripoutとnbdimeを使用する
  2. .py ファイルで管理するなら # %% を使う

特に2の方法では .py ファイルで # %% を使えば、.ipynb と同じように実行できるので、Git管理の手間を省けます。

GitとJupyter Notebookの相性について

Jupyter NotebookがGitと相性が悪い主な理由はJSON形式で保存されることにあります。

  • 実行結果やメタデータが含まれる
    • コードに変更がなくても、出力結果をクリアすると変更として認識されてしまう
  • 不要な差分が発生する
    • Gitの差分確認時にメタデータの変更が表示され、視認性が悪くなる

このため、Jupyter NotebookをGitで管理するとメタデータの差異を手動で無視する必要があり、非常に面倒です。

解決方法1: nbstripoutとnbdimeライブラリを使用する

.ipynb をGitで管理したい場合、nbstripout を使用すると、出力やメタデータを削除できます。nbdimeを使用すると差分表示がしやすくなります。

1. nbstripout のインストール

pip install nbstripout

2. Gitリポジトリで nbstripoutとnbdimeを有効化

nbstripout --install --attributes .gitattributes
nbdime config-git --enable

この設定を行うと、nbstripoutで.ipynbをコミットする際に出力やメタデータの差分が無視されるようになります。nbdimeで差分表示を分かりやすくしてくれます。今回は.gitattributesファイルを作りましたがグローバルに適用したい場合は --globalなどのオプションも使用できます。ただしnbdimeはローカルでの差分を見やすくしてくれるものです。誰かが書いたjupyter notebookをコードレビューしたい場合などは、あまり効力が発揮しません。

解決方法2: jupytext ライブラリを使用

jupytext を使うと、.ipynb を .py に変換し、双方向で同期できるようになります。

1. jupytext のインストール

pip install jupytext

2. .py ファイルに変換

jupytext --set-formats ipynb,py my_notebook.ipynb

この方法を使うと、.py をGitで管理しつつ、Notebook形式にも変換できます。

VSCodeでの利用

ただし、VSCodeでの自動同期には標準機能がなく、拡張機能が必要になります。

VSCode拡張機能: Jupytext

利用者が少ないようですが、VSCodeで .py と .ipynb を同期したい場合には便利です。

解決方法3: # %% を使用する

実は、Jupyter Notebookを使わなくても、Pythonのスクリプト (.py) に # %% を使えば、セルごとに実行できます。

# %%
import os
print("Hello")

この方法を使えば、.py ファイルだけをGitで管理しながら、Jupyter Notebookのような使い勝手を維持できます。

まとめ

管理方法 特徴
.ipynb をGitで管理 nbstripout を使って出力やメタデータを削除
.py で管理 # %% を使えばJupyter Notebook風に運用可能
.ipynb と .py を同期 jupytext を使用（ただしVSCodeでは拡張機能が必要？）

参考

さいごに

Gitの学習中に疑問に思ったことが解決してスッキリしました。
最近 .ipynb の利用が減っているのかどうか、少し気になりますね。

Discussion