nbdime

nbdime provides specialized tools for diffing and merging Jupyter Notebooks. The core toolset includes:

• nbdiff: Compares notebooks in a terminal-friendly format.
• nbmerge: Performs a three-way merge of notebooks with automatic conflict resolution.
• nbdiff-web: Displays a rich, rendered diff of notebooks in a web browser.
• nbmerge-web: Provides a web-based interface for three-way notebook merging.
• nbshow: Presents a single notebook in a terminal-friendly way.

nbdime is designed for two primary categories of use:

1. Version Control Integration: Acting as a merge command to handle notebook conflicts during version control operations.
2. Inspection and Testing: Acting as a diff command for inspecting changes manually or performing automated regression testing.

The core functionality relies on diff algorithms that handle both text in source cells and various data formats in output cells based on their MIME types.

A merge decision is an object that describes a specific part of a merge operation between two objects that share a common base. It contains:

• Information about local changes.
• Information about remote changes.
• The decision taken to resolve the merge.

When performing a three-way merge using base, local, and remote objects, nbdime produces two outputs:

1. A fully or partially merged object.
2. A set of merge decision objects that describe how each change was handled.

If you are developing nbdime and need to use the development versions of the notebook and lab extensions, run the following commands after your pip development installation.

Note: Only run one of the following two server commands; running both may cause issues.

• For JupyterLab or nbclassic development: jupyter server extension enable nbdime
• For JupyterLab extension development: jupyter labextension develop --overwrite .

Rebuilding Extensions: If you modify front-end code, rebuild the extensions from the repository root using npm run build. If you modify the server extension, you must restart the server to apply changes.

If you require granular control instead of using the nbdime extensions wrapper, you can install the components individually using the following sequence:

1. Enable the notebook server extension.
2. Install and enable the notebook frontend extension.
3. Install the JupyterLab frontend extension.

Use --sys-prefix, --user, or --system flags as needed to manage installation scope.

To set up the environment for running tests, install the project with the [test] extra using pip.

pip install .[test]

The easiest way to create new integration tests is to use the Playwright code generator. This requires the extension to be compiled and installed in JupyterLab.

1. Compile and install dependencies (see Set up and run nbdime-ui-tests).
2. Start the server in one terminal:

   cd ./ui-tests
   npm start

3. Run the code generator in a separate terminal:

   cd ./ui-tests
   npm playwright codegen localhost:8888

# Terminal 1
cd ./ui-tests
npm start

# Terminal 2
cd ./ui-tests
npm playwright codegen localhost:8888

You can perform content-aware diffing of Jupyter notebooks using either the terminal or a web-based interface.

• Use nbdiff for a terminal-based diff.
• Use nbdiff-web for a rich, web-based rendering of the diff.

To improve how Git handles notebook diffs and merges, you can configure Git to use nbdime drivers globally. This enables both diff and merge tools for notebooks within your Git workflows.

nbdime config-git --enable --global