nb-clean

What it is and what it does

nb-clean is a command-line tool and Python library that strips transient metadata from Jupyter notebooks—execution counts, cell outputs, and notebook metadata—to reduce noise in version control diffs. It works by removing information that changes every time a notebook is run but carries no semantic value for code review or collaboration.

The package integrates directly into your Git workflow via a configurable filter (which cleans notebooks as they're staged) or as a pre-commit hook (which modifies notebooks on disk before commit). It can also be used standalone to check whether a notebook is clean or to clean notebooks in place. Fine-grained flags let you preserve specific metadata fields (like tags for tools such as papermill) or outputs when needed.

Use it for:

• Automatically clean notebooks before each Git commit using a pre-commit hook to keep diffs focused on actual code changes.
• Check notebooks in CI pipelines to enforce that committed notebooks contain no execution counts or stale outputs.
• Preserve specific cell metadata fields (e.g., tags) while removing outputs, for workflows that rely on notebook annotations.
• Use as a Git filter to clean notebooks on staging without modifying your local working copy.
• Integrate into a Python script to programmatically clean or validate notebooks as part of a data pipeline.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

nb-clean removes execution counts, metadata, and outputs from Jupyter notebooks to prepare them for version control, and can automatically clean notebooks via Git filters or pre-commit hooks.

Yes. nb-clean solves a real problem for teams using Jupyter in version control: it eliminates noise from execution state and metadata, making diffs readable and reducing merge conflicts. The package is stable (Production/Stable status), actively maintained, has no known vulnerabilities, and integrates seamlessly into standard Git workflows. Install it if you commit notebooks to Git.

Install

nb-clean on PyPI

pip install nb-clean

uv add nb-clean

poetry add nb-clean

Installing nb-clean

Before you install

Low install friction with a single runtime dependency (nbformat). Active maintenance with recent commits and a stable release history since 2017. Supports Python 3.9 through 3.13.

License in practice

ISC license is permissive and imposes minimal restrictions; you can use, modify, and distribute nb-clean freely in commercial and private projects.

Quickstart

pip install nb-clean
nb-clean check notebook.ipynb
nb-clean clean notebook.ipynb

Requires Python 3.9 or later.

Verify before relying

• Whether the Git filter approach preserves working-directory visibility of outputs as claimed in the description.
• Performance characteristics when processing large notebooks or batch operations.

Package facts

Evidence: nb_clean-4.0.1-py3-none-any.whl

Keywords: jupyter, notebook, clean, filter, git

Tags

More Software Development packages