---
id: nb-clean
version: "4.0.1"
license: ISC
license_treatment: permissive
maintenance: active
---

# nb-clean — Clean Jupyter notebooks for versioning

License: permissive · Maintenance: active · Downloads: 111.3K/mo

## 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 above — 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

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

- License: ISC (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 111.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

jupyter notebook version control, clean notebook metadata, git filter jupyter, pre-commit hook notebooks, remove notebook outputs, notebook execution counts, jupyter git integration, jupyter-workflow, git-integration, notebook-cleaning

[View on SkillFed](https://skillfed.io/packages/nb-clean) · [View on PyPI](https://pypi.org/project/nb-clean/)