nb-clean
raw JSON → 4.0.1 verified Fri May 01 auth: no python
A tool to clean Jupyter notebooks for version control, removing cell outputs, execution counts, and metadata. Current version is 4.0.1, released March 2025. Release cadence is irregular, with major versions dropping support for old Python releases.
pip install nb-clean Common errors
error nb-clean: error: unrecognized arguments: --preserve-cell-metadata ↓
cause The --preserve-cell-metadata flag expects a value to specify which metadata keys to preserve, but the user passed it without a value or with a space-separated list.
fix
Use the flag with a comma-separated list: --preserve-cell-metadata key1,key2
error ModuleNotFoundError: No module named 'nb_clean' ↓
cause Trying to import nb-clean as a Python module. nb-clean is a command-line tool, not a library.
fix
Do not import; run as a CLI command: nb-clean clean notebook.ipynb
Warnings
breaking Version 4.0.0 drops support for Python 3.8. Users on Python 3.8 must stay on nb-clean <4.0.0 or upgrade Python. ↓
fix Upgrade Python to >=3.9 or pin nb-clean to <4.0.0.
breaking Version 3.0.0 drops support for Python 3.7. Users on Python 3.7 must stay on nb-clean <3.0.0 or upgrade Python. ↓
fix Upgrade Python to >=3.8 or pin nb-clean to <3.0.0.
gotcha By default, nb-clean removes all cell outputs, execution counts, and cell metadata. If you want to preserve outputs, use the --preserve-cell-outputs flag. Preserving execution counts requires --preserve-execution-counts, and preserving notebook metadata (like kernel info) requires --preserve-notebook-metadata. ↓
fix Use appropriate flags: -o (preserve cell outputs), -c (preserve execution counts), -n (preserve notebook metadata).
Quickstart
# Clean a notebook in-place
nb-clean clean notebook.ipynb
# Check if a notebook is clean
nb-clean check notebook.ipynb