Package: nb-clean
nb-cleancleans Jupyter notebooks of cell execution counts, metadata, outputs,
and (optionally) empty cells, preparing them for committing to version control.
It provides both a Git filter and pre-commit hook to automatically clean
notebooks before they're staged, and can also be used with other version control
systems, as a command line tool, and as a Python library. It can determine if a
notebook is clean or not, which can be used as a check in your continuous
integration pipelines.[!NOTE]nb-clean2.0.0 introduced a new command line interface to make cleaning
notebooks in place easier. If you upgrade from a previous release, you'll need
to migrate to the new interface as described underMigrating tonb-clean2.InstallationTo install the latest release fromPyPI, usepip:python3-mpipinstallnb-cleannb-cleancan also be installed withConda:condainstall-cconda-forgenb-cleanIn Python projects usingPoetryorPDMfor dependency management, addnb-cleanas a development dependency withpoetry add --group dev nb-cleanorpdm add --dev nb-clean.nb-cleanrequires Python 3.8 or later.UsageCheckingYou can check if a notebook is clean with:nb-cleanchecknotebook.ipynbor by passing the notebook contents on standard input:nb-cleancheck<notebook.ipynbTo also check for empty cells, add the-e/--remove-empty-cellsflag. To
ignore cell metadata, add the-m/--preserve-cell-metadataflag, optionally
with a selection of metadata fields to ignore. To ignore cell outputs, add the-o/--preserve-cell-outputsflag. To ignore cell execution counts, add the-c/--preserve-execution-countsflag. To ignore notebook metadata, such as
language version, add the-n/--preserve-notebook-metadataflag.nb-cleanwill exit with status code 0 if the notebook is clean, and status
code 1 if it is not.nb-cleanwill also print details of cell execution
counts, metadata, outputs, and empty cells it finds.Cleaning (interactive)You can clean a Jupyter notebook with:nb-cleancleannotebook.ipynbThis cleans the notebook in place. You can also pass the notebook content on
standard input, in which case the cleaned notebook is written to standard
output:nb-cleanclean<original.ipynb>cleaned.ipynbTo also remove empty cells, add the-e/--remove-empty-cellsflag. To
preserve cell metadata, add the-m/--preserve-cell-metadataflag, optionally
with a selection of metadata fields to preserve. To preserve cell outputs, add
the-o/--preserve-cell-outputsflag. To preserve cell execution counts, add
the-c/--preserve-execution-countsflag. To preserve notebook metadata, such
as language version, add the-n/--preserve-notebook-metadataflag.Cleaning (Git filter)To add a filter to an existing Git repository to automatically clean notebooks
when they're staged, run the following from the working tree:nb-cleanadd-filterThis will configure a filter to remove cell execution counts, metadata, and
outputs. To also remove empty cells, use:nb-cleanadd-filter--remove-empty-cellsTo preserve cell metadata, such as that required by tools such aspapermill,
use:nb-cleanadd-filter--preserve-cell-metadataTo preserve only specific cell metadata, e.g.,tagsandspecial, use:nb-cleanadd-filter--preserve-cell-metadatatagsspecialTo preserve cell outputs, use:nb-cleanadd-filter--preserve-cell-outputsTo preserve cell execution counts, use:nb-cleanadd-filter--preserve-execution-countsTo preserve notebook metadata, such as language version, use:nb-cleanadd-filter--preserve-notebook-metadatanb-cleanwill configure a filter in the Git repository in which it is run, and
won't mutate your global or system Git configuration. To remove the filter, run:nb-cleanremove-filterCleaning (pre-commit hook)nb-cleancan also be used as apre-commithook. You may prefer this to the
Git filter if your project already uses the pre-commit framework.Note that the Git filter and pre-commit hook work differently, with different
effects on your working directory. The pre-commit hook operates on the notebook
on disk, cleaning the copy in your working directory. The Git filter cleans
notebooks as they are added to the index, leaving the copy in your working
directory dirty. This means cell outputs are still visible to you in your local
Jupyter instance when using the Git filter, but not when using the pre-commit
hook.After installingpre-commit, add thenb-cleanhook by adding the following
snippet to.pre-commit-config.yamlin the root of your repository:repos:-repo:https://github.com/srstevenson/nb-cleanrev:3.2.0hooks:-id:nb-cleanYou can pass additional arguments tonb-cleanwith anargsarray. The
following example shows how to preserve only two specific metadata fields. Note
that, in the example, the final item--in the arg list is mandatory. The
option--preserve-cell-metadatamay take an arbitrary number of field
arguments, and the--argument is needed to separate them from notebook
filenames, whichpre-commitwill append to the list of arguments.repos:-repo:https://github.com/srstevenson/nb-cleanrev:3.2.0hooks:-id:nb-cleanargs:---remove-empty-cells---preserve-cell-metadata-tags-slideshow---Runpre-commit installto ensure the hook is installed, andpre-commit autoupdateto update the hook to the latest release ofnb-clean.Preserving all nbformat metadataTo ignore or preserve specifically the metadata defined in thenbformatdocumentation,
use the following options:--preserve-cell-metadata collapsed scrolled deletable editable format name tags jupyter execution.Migrating tonb-clean2The following table maps from the command line interface ofnb-clean1.6.0 to
that ofnb-clean>=2.0.0.Descriptionnb-clean1.6.0nb-clean>=2.0.0Clean notebooknb-clean clean -i/--input notebook.ipynb | sponge notebook.ipynbnb-clean clean notebook.ipynbClean notebook (remove empty cells)nb-clean clean -i/--input notebook.ipynb -e/--remove-emptynb-clean clean notebook.ipynb -e/--remove-empty-cellsClean notebook (preserve cell metadata)nb-clean clean -i/--input notebook.ipynb -m/--preserve-metadatanb-clean clean notebook.ipynb -m/--preserve-cell-metadataCheck notebooknb-clean check -i/--input notebook.ipynbnb-clean check notebook.ipynbCheck notebook (ignore non-empty cells)nb-clean check -i/--input notebook.ipynb -e/--remove-emptynb-clean check notebook.ipynb -e/--remove-empty-cellsCheck notebook (ignore cell metadata)nb-clean check -i/--input notebook.ipynb -m/--preserve-metadatanb-clean check notebook.ipynb -m/--preserve-cell-metadataAdd Git filter to clean notebooksnb-clean configure-gitnb-clean add-filterRemove Git filternb-clean unconfigure-gitnb-clean remove-filterCopyrightCopyright ©Scott Stevenson.nb-cleanis distributed under the terms of theISC license.