Install & Compatibility
Where this runs
tested against v4.0.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 92.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 9.5s · import 0.000s · 90MB
93MB installed
● package 93MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
diff_notebooks
✓ from nbdime import diff_notebooks
✗ from nbdime.diff_files import diff_notebooks
This quickstart demonstrates how to create two simple Jupyter notebooks and then use the `nbdime` command-line tool to perform a diff between them, showing the output directly in the terminal. The default `nbdime diff` command would open a browser for a richer visual diff.
import nbformat
from pathlib import Path
import subprocess
# Create two dummy notebooks for demonstration
nb1 = nbformat.v4.new_notebook()
nb1.cells.append(nbformat.v4.new_code_cell("print('Hello from A')"))
nb1_path = Path("notebook_a.ipynb")
with open(nb1_path, "w", encoding="utf-8") as f:
nbformat.write(nb1, f)
nb2 = nbformat.v4.new_notebook()
nb2.cells.append(nbformat.v4.new_code_cell("print('Hello from B')"))
nb2.cells.append(nbformat.v4.new_markdown_cell("## A new section\nThis is a new section in notebook B."))
nb2_path = Path("notebook_b.ipynb")
with open(nb2_path, "w", encoding="utf-8") as f:
nbformat.write(nb2, f)
print(f"Created {nb1_path} and {nb2_path}")
# Run nbdime diff from the command line
print("\n--- Running nbdime diff in terminal mode ---")
try:
# Use --diff-alg=terminal to get output directly in the console
result = subprocess.run(
["nbdime", "diff", str(nb1_path), str(nb2_path), "--diff-alg=terminal"],
capture_output=True, text=True, check=True
)
print(result.stdout)
except subprocess.CalledProcessError as e:
print(f"Error running nbdime diff: {e.stderr}")
# To open in a browser (default behavior if --diff-alg is not specified)
# print("\n--- Running nbdime diff in browser (opens new tab) ---")
# subprocess.Popen(["nbdime", "diff", str(nb1_path), str(nb2_path)])
# print("Check your browser for the visual diff. Press Ctrl+C to stop this script after viewing.")
# import time; time.sleep(10) # Give time to view, then uncomment cleanup
# Clean up
nb1_path.unlink()
nb2_path.unlink()
print(f"\nCleaned up {nb1_path} and {nb2_path}")
nbdime --version
Debug
Known issues
breakingnbdime 3.x and newer require Python 3.6+ for installation and execution. Older Python environments (e.g., Python 2.7, Python 3.5) are no longer supported and will lead to installation failures or runtime errors.fixUpgrade your Python environment to 3.6 or a newer version (e.g., 3.9, 3.10, 3.11).
affects: <3.x
breakingWith `nbdime` version 4.0.0 and above, the JupyterLab frontend extension installation process changed. For JupyterLab 4, `pip install nbdime` should automatically handle the frontend extension. However, for JupyterLab 3 and below, you still need to explicitly run `jupyter labextension install @jupyterlab/nbdime-extension` (and possibly specify a compatible version like `@3`) after installing the Python package.fixFor JupyterLab 4, `pip install nbdime` should be sufficient. For JupyterLab 3, ensure you run `jupyter labextension install @jupyterlab/nbdime-extension` (or `@jupyterlab/nbdime-extension@3`) after `pip install nbdime`.
affects: >=4.0.0 (JupyterLab 4 vs. 3)
gotchaBy default, `nbdime diff` and `nbdime merge` commands launch a web browser to display the visual diff/merge interface. Users expecting immediate terminal output may be surprised. For command-line diff output, use the `--diff-alg=terminal` flag.fixTo get terminal output, use `nbdime diff --diff-alg=terminal file1.ipynb file2.ipynb`. To prevent browser launch, use `--browser=none`.
affects: All versions
deprecatedThe `ipython_genutils` dependency was removed in `nbdime` version 3.2.0. While this is an improvement, environments with other packages that still explicitly rely on or bundle `ipython_genutils` might experience minor dependency conflicts or warnings during upgrades.fixEnsure all other packages in your environment are up-to-date. If issues persist, consider isolating `nbdime` in a virtual environment.
affects: >=3.2.0
Upgrade
Version history
4.0.4latest on PyPI · released Feb 10, 2026
Audit
Dependencies
nbformatrequiredCore dependency for notebook structure parsing.
notebookrequiredFor integration with classic Jupyter Notebook and server functionalities.
jupyter_serverrequiredUnderpins the JupyterLab/Notebook server and extension architecture.