Convenient diff of Jupyter Notebooks in PyCharm

[xandrd]

Hello everyone,

I'd like to share a solution for more convenient analysis of differences (e.g., diff) in Jupyter Notebooks using PyCharm. The default diff tool in PyCharm compares notebooks by their raw JSON representation, which is not convenient. However, there's a third-party tool called nbdime that offers a content-aware diff.

I came across a discussion on Stack Overflow about integrating nbdime with PyCharm. I'd like to share the steps for setting it up.

TL;DR (short version)

Installation:

pip install nbdime
pip install jupyter-server==2.12.5

Configuration:

1. Navigate to File -> Preferences -> Tools -> Diff & Merge -> External Diff.
2. Add nbdiff-web.exe (located in venv\Scripts\nbdiff-web.exe) with the arguments:
   --ignore-details --ignore-metadata --ignore-outputs %1 %2.
3. Associate Jupyter with the new external diff tool.

Usage:

Right-click on the notebook and select Git -> Show Diff.

---

Step 1: Install nbdime

You can install nbdime using your terminal:

pip install nbdime

Alternatively, you can use PyCharm’s package manager:

Important

The latest version (4.0.1) of nbdime has a known issue with the Jupyter server. To avoid this, install version 2.12.5 of the Jupyter server:

pip install jupyter-server==2.12.5

---

Step 2: Configuring PyCharm

1. In PyCharm, go to File -> Preferences -> Tools -> Diff & Merge -> External Diff Tools, and enable external tools.
2. Click + to add a new tool, then navigate to your Python environment to find nbdiff-web. For Windows, this is usually located in the Scripts folder as nbdiff-web.exe.
3. Add the following argument pattern (see more details here):
   --ignore-details --ignore-metadata --ignore-outputs %1 %2.
4. Click OK.
   

Next, associate the external diff tool with Jupyter notebooks:

• In the relevant section, click +, select Jupyter, and choose nbdiff-web as the diff tool.
  

---

Step 3: Usage

From now on, when you double-click a Jupyter notebook in the commit view, the differences will be displayed in your external browser rather than in PyCharm.

Alternatively, right-click on a notebook and select Git -> Show Diff.

---

I hope this helps streamline your workflow when working with Jupyter notebooks in PyCharm!

[jameswilburlewis]

I just tried it....seems to work well!

The latest nbdime release (4.0.2) may have fixed the jupyter-server incompatibility issue. My installation was pretty old, so I just updated to the latest jupyter-server version 2.14.2, and that seems to work. I haven't tried any of the older releases.

When you're looking for the nbdiff-web program to update your Pycharm preferences, if you happen to be on a Mac, I found it in venv/bin in the virtual environment I'm using. Also, instead of File->Preferences->Tools, I had to go to Pycharm->Settings->Tools, or click the gear icon for "IDE and Project Settings" in the upper right and navigate to Tools.