nbdime – diffing and merging of Jupyter Notebooks

Version: 0.1

nbdime provides tools for diffing and merging Jupyter notebooks.

example of nbdime nbdiff-web

Figure: nbdime example

Abstract

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:

diff example using traditional line-based diff tool

Figure: diff using traditional line-based diff tool

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:

example of nbdime's content-aware diff

Figure: nbdime’s content-aware diff

Quickstart

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 nbdime 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.

To configure git to use nbdime to as a command-line driver to diff and merge notebooks:

git-nbdiffdriver config --enable --global
git-nbmergedriver config --enable --global

Now when you do git diff or git merge with notebooks, you should see a nice diff view, like this:

nbdime's command-line diff

Figure: nbdime’s ‘content-aware’ command-line diff

To configure git to use the web-based GUI viewers of notebook diffs and merges:

git-nbdifftool config --enable --global
git-nbmergetool config --enable --global

With these, you can trigger the tools with:

git difftool --tool nbdime [ref [ref]]
example of nbdime's content-aware diff

Figure: nbdime’s content-aware diff

and:

git mergetool --tool nbdime
nbdime's merge with web-based GUI viewer

Figure: nbdime’s merge with web-based GUI viewer

Note

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.

For more detailed information on integrating nbdime with version control, see Version control integration.