nbdime – diffing and merging of Jupyter Notebooks¶
nbdime provides tools for diffing and merging Jupyter notebooks.
Why is nbdime needed?¶
Jupyter notebooks are useful, rich media documents stored in a plain text JSON format. This format is relatively easy to parse. However, primitive line-based diff and merge tools do not handle well the logical structure of notebook documents. These tools yield diffs like this:
nbdime, on the other hand, provides “content-aware” diffing and merging of Jupyter notebooks. It understands the structure of notebook documents. Therefore, it can make intelligent decisions when diffing and merging notebooks, such as:
- eliding base64-encoded images for terminal output
- using existing diff tools for inputs and outputs
- rendering image diffs in a web view
- auto-resolving conflicts on generated values such as execution counters
nbdime yields diffs like this:
To get started with nbdime, install with pip:
pip install nbdime
And you can be off to the races by diffing notebooks in your terminal with nbdiff:
nbdiff notebook_1.ipynb notebook_2.ipynb
or viewing a rich web-based rendering of the diff with nbdiff-web:
nbdiff-web notebook_1.ipynb notebook_2.ipynb
For more information about nbdime’s commands, see Console commands.
Git integration quickstart¶
Many of us who are writing and sharing notebooks do so with git and GitHub. Git doesn’t handle diffing and merging notebooks very well by default, but you can configure git to use nbdime and it will get a lot better.
The quickest way to get set up for git integration is to call:
nbdime config-git --enable --global
This will enable the both the drivers and the tools for both diff and merge.
Now when you do git diff or git merge with notebooks, you should see a nice diff view, like this:
To use the web-based GUI viewers of notebook diffs, call:
git difftool --tool nbdime [ref [ref]]
Using git-nbdiffdriver config overrides the ability to call git difftool with notebooks.
You can still call nbdiff-web to diff files directly, but getting the files from git refs is still on our TODO list.
If you have a merge conflict in a notebook, the merge driver will ensure that the conflicted notebook is a valid notebook that can be viewed in the normal notebook viewer. In it, the conflicts will be marked similarly to how git would normally indicate conflicts, and they can be resolved manually. Alternatively, nbdime provides a web-base mergetool for visualizing and resolving merge conflicts, and it can be launched by calling:
For more detailed information on integrating nbdime with version control, see Version control integration.