Package: nbstripout
nbstripout: strip output from Jupyter and IPython notebooksReads a notebook from a file or stdin, strips output and some metadata, and
writes the "cleaned" version of the notebook to the original file or stdout.Intended to be used as a Git filter or pre-commit hook for users who don't want
to track output in Git.Roughly equivalent to the "Clear All Output" command in the notebook UI, but
only "visible" to Git: keep your output in the file on disk, but don't commit
the output to Git. This helps minimizing diffs and reduce file size.Originally based onhttps://gist.github.com/minrk/6176788.Python 3 onlyAs of version 0.4.0, nbstripout supports Python 3only. If you need to use
Python 2.7, install nbstripout 0.3.10:pip install nbstripout==0.3.10ScreencastThis screencast demonstrates the use and working principles behind the
nbstripout utility and how to use it as a Git filter:InstallationYou can download and install the latest version ofnbstripoutfrom the Python
package indexPyPIas follows:pip install --upgrade nbstripoutWhen using theAnacondaPython
distribution, installnbstripoutvia thecondapackage manager fromconda-forge:conda install -c conda-forge nbstripoutUsageStrip output from IPython / Jupyter / Zeppelin notebook (modifies the file
in-place):nbstripout FILE.ipynb [FILE2.ipynb ...]
nbstripout FILE.zplnForce processing of non.ipynbfiles:nbstripout -f FILE.ipynb.bakFor using Zeppelin mode while processing files with other extensions use:nbstripout -m zeppelin -f <file.ext>Write to stdout e.g. to use as part of a shell pipeline:cat FILE.ipynb | nbstripout > OUT.ipynb
cat FILE.zpln | nbstripout -m zeppelin > OUT.zplnornbstripout -t FILE.ipynb | other-commandSet up the git filter and attributes as described in the manual installation
instructions below:nbstripout --installSet up the git filter using.gitattributes:nbstripout --install --attributes .gitattributesSpecify a different path to the Python interpreter to be used for the git
filters (default is the path to the Python interpreter used whennbstripoutis
installed). This is useful if you have Python installed in different or unusual
locations across machines, e.g./usr/bin/python3on your machine vs/usr/local/bin/python3in a container or elsewhere.nbstripout --install --python python3Using justpython3lets each machine find its Python itself. However, keep in
mind that depending on your setup this might not be the Python version you want
or even fail because an absolute path is required.Set up the git filter in your global~/.gitconfig:nbstripout --install --globalSet up the git filter in your system-wide$(prefix)/etc/gitconfig(most
installations will require you tosudo):[sudo] nbstripout --install --systemRemove the git filter and attributes:nbstripout --uninstallRemove the git filter from your global~/.gitconfigand attributes:nbstripout --uninstall --globalRemove the git filter from your system-wide$(prefix)/etc/gitconfigand
attributes:[sudo] nbstripout --uninstall --systemRemove the git filter and attributes from.gitattributes:nbstripout --uninstall --attributes .gitattributesCheck ifnbstripoutis installed in the current repository (exits with code 0
if installed, 1 otherwise):nbstripout --is-installedPrint status ofnbstripoutinstallation in the current repository and
configuration summary of filter and attributes if installed (exits with code 0
if installed, 1 otherwise):nbstripout --statusDo a dry run and only list which files would have been stripped:nbstripout --dry-run FILE.ipynb [FILE2.ipynb ...]Print the version:nbstripout --versionShow help and usage instructions:nbstripout --helpConfiguration filesThe following table shows in which files thenbstripoutfilter and attribute
configuration is written to for given extra flags to--installand--uninstall:flagsfiltersattributesnone.git/config.git/info/attributes--global~/.gitconfig~/.config/git/attributes--system$(prefix)/etc/gitconfig$(prefix)/etc/gitattributes--attributes=.gitattributes.git/config.gitattributes--global --attributes=.gitattributes~/.gitconfig.gitattributesInstall globallyUsually,nbstripoutis installed per repository so you can choose where to use
it or not. You can choose to set the attributes in.gitattributesand commit
this file to your repository, however there is no way to have git set up the
filters automatically when someone clones a repository. This is by design, to
prevent you from executing arbitrary and potentially malicious code when cloning
a repository.To installnbstripoutfor all your repositories such that you no longer need
to run the installation once per repository, install as follows:mkdir -p ~/.config/git  # This folder may not exist
nbstripout --install --global --attributes=~/.config/git/attributesThis will set up the filters and diff driver in your~/.gitconfigand instruct
git to apply them to any.ipynbfile in any repository.Note that you need to uninstall with the same flags:nbstripout --uninstall --global --attributes=~/.config/git/attributesInstall system-wideTo installnbstripoutsystem-wide so that it applies to all repositories for
all users, install as follows (most installations will require you tosudo):[sudo] nbstripout --install --systemThis will set up the filters and diff driver in$(prefix)/etc/gitconfigand
instruct git to apply them to any.ipynbfile in any repository for any user.Note that you need to uninstall with the same flags:[sudo] nbstripout --uninstall --systemApply retroactivelynbstripoutcan be used to rewrite an existing Git repository usinggit filter-branchto strip output from existing notebooks. This invocation
uses--index-filterand operates on all ipynb-files in the repo: :git filter-branch -f --index-filter '
    git checkout -- :*.ipynb
    find . -name "*.ipynb" -exec nbstripout "{}" +
    git add . --ignore-removal
'If the repository is large and the notebooks are in a subdirectory it will run
faster withgit checkout -- :<subdir>/*.ipynb. You will get a warning for
commits that do not contain any notebooks, which can be suppressed by piping
stderr to/dev/null.This is a potentially slower but simpler invocation using--tree-filter:git filter-branch -f --tree-filter 'find . -name "*.ipynb" -exec nbstripout "{}" +'Removing empty cellsDrop empty cells i.e. cells wheresourceis either empty or only contains
whitespace:nbstripout --drop-empty-cellsRemoving [init]{.title-ref} cellsBy defaultnbstripoutwill keep cells withinit_cell: truemetadata. To
disable this behavior use:nbstripout --strip-init-cellsRemoving entire cellsIn certain conditions it might be handy to remove not only the output, but the
entire cell, e.g. when developing exercises.To drop all cells tagged with "solution" run:nbstripout --drop-tagged-cells="solution"The option accepts a list of tags separated by whitespace.Keeping some outputDo not strip the execution count/prompt number:nbstripout --keep-countDo not strip outputs that are smaller that a given max size (useful for removing
only large outputs like images):nbstripout --max-size 1kDo not strip the output, only metadata:nbstripout --keep-outputDo not reassign the cell ids to be sequential (which is the default behavior):nbstripout --keep-idTo mark special cells so that the output is not stripped, you can either:Set thekeep_outputtag on the cell. To do this, enable the tags toolbar
(View > Cell Toolbar > Tags) and then add thekeep_outputtag for each
cell you would like to keep the output for.Set the"keep_output": truemetadata on the cell. To do this, select the
"Edit Metadata" Cell Toolbar, and then use the "Edit Metadata" button on
the desired cell to enter something like:{
  "keep_output": true,
}You can also keep output for an entire notebook. This is useful if you want to
strip output by default in an automated environment (e.g. CI pipeline), but want
to be able to keep outputs for some notebooks. To do so, add the option above to
thenotebookmetadata instead. (You can also explicitly remove outputs from a
particular cell in these notebooks by adding a cell-level metadata entry.)Another use-case is to preserve initialization cells that might load customized
CSS etc. critical for the display of the notebook. To support this, we also keep
output for cells with:{
  "init_cell": true,
}This is the same metadata used by theinit_cell nbextension.Stripping metadataThe following metadata is stripped by default:Notebook metadata:signature,widgetsCell metadata:ExecuteTime,collapsed,execution,heading_collapsed,hidden,scrolledAdditional metadata to be stripped can be configured via eithergit config (--global/--system) filter.nbstripout.extrakeys, e.g. :git config --global filter.nbstripout.extrakeys '
  metadata.celltoolbar
  metadata.kernelspec
  metadata.language_info.codemirror_mode.version
  metadata.language_info.pygments_lexer
  metadata.language_info.version
  metadata.toc
  metadata.notify_time
  metadata.varInspector
  cell.metadata.heading_collapsed
  cell.metadata.hidden
  cell.metadata.code_folding
  cell.metadata.tags
  cell.metadata.init_cell'the--extra-keysflag, which takes a space-delimited string as an
argument, e.g. :--extra-keys="metadata.celltoolbar cell.metadata.heading_collapsed"Note: Only notebook and cell metadata is currently supported and every key
specified viafilter.nbstripout.extrakeysor--extra-keysmust start withmetadata.for notebook andcell.metadata.for cell metadata.You can keep certain metadata that would be stripped by default with eithergit config (--global/--system) filter.nbstripout.keepmetadatakeys, e.g.:git config --global filter.nbstripout.keepmetadatakeys '
  cell.metadata.collapsed
  cell.metadata.scrolled'the--keep-metadata-keysflag, which takes a space-delimited string as an
argument, e.g.:--keep-metadata-keys="cell.metadata.collapsed cell.metadata.scrolled"Note: Previous versions of Jupyter usedmetadata.kernel_specfor kernel
metadata. Prefer strippingkernelspecentirely: only stripping some attributes
insidekernelspecmay lead to errors when opening the notebook in Jupyter (see#141).Excluding files and foldersTo exclude specific files or folders from being processed by thenbstripoutfilters, add the path and exception to your filter specifications defined in.git/info/attributesor.gitattributes:docs/** filter= diff=This will disablenbstripoutfor any file in thedocsdirectory.:notebooks/Analysis.ipynb filter= diff=This will disablenbstripoutfor the fileAnalysis.ipynblocated in thenotebooksdirectory.To check which attributes a given file has with the current config, run:git check-attr -a -- path/to/fileFor a file to which the filter applies you will see the following:$ git check-attr -a -- foo.ipynb
foo.ipynb: diff: ipynb
foo.ipynb: filter: nbstripoutFor a file in your excluded folder you will see the following:$ git check-attr -a -- docs/foo.ipynb
foo.ipynb: diff:
foo.ipynb: filter:Manual filter installationSet up a git filter and diff driver using nbstripout as follows:git config filter.nbstripout.clean '/path/to/nbstripout'
git config filter.nbstripout.smudge cat
git config filter.nbstripout.required true
git config diff.ipynb.textconv '/path/to/nbstripout -t'This will add a section to the.git/configfile of the current repository.If you want the filter to be installed globally for your user, add the--globalflag to thegit configinvocations above to have the configuration
written to your~/.gitconfigand apply to all repositories.If you want the filter to be installed system-wide, add the--systemflag to
thegit configinvocations above to have the configuration written to$(prefix)/etc/gitconfigand apply to all repositories for all users.Create a file.gitattributes(if you want it versioned with the repository) or.git/info/attributes(to apply it only to the current repository) with the
following content:*.ipynb filter=nbstripout
*.ipynb diff=ipynbThis instructs git to use the filter namednbstripoutand the diff driver
namedipynbset up in the git config above for every.ipynbfile in the
repository.If you want the attributes be set for.ipynbfiles in any of your git
repositories, add those two lines to~/.config/git/attributes. Note that this
file and the~/.config/gitdirectory may not exist.If you want the attributes be set for.ipynbfiles in any git repository on
your system, add those two lines to$(prefix)/etc/gitattributes. Note that
this file may not exist.Usingnbstripoutas a pre-commit hookpre-commitis a framework for managing gitpre-commit hooks.Once you havepre-commitinstalled, add the following
to the.pre-commit-config.yamlin your repository:repos:
- repo: https://github.com/kynan/nbstripout
  rev: 0.7.1
  hooks:
    - id: nbstripoutThen runpre-commit installto activate the hook.[!WARNING]In this mode,nbstripoutis used as a git hook to strip any.ipynbfiles
before committing. This also modifies your working copy!In its regular mode,nbstripoutacts as a filter and only modifies what git
gets to see for committing or diffing. The working copy stays intact.TroubleshootingKnown issuesCertain Git workflows are not well supported bynbstripout:Local changes to notebook files that are made invisible to Git due to thenbstripoutfilter do still cause conflicts when attempting to sync
upstream changes (git pull,git mergeetc.). This is because Git has no
way of resolving a conflict caused by a non-stripped local file being merged
with a stripped upstream file.  Addressing this issue is out of scope fornbstripout. Read more and find workarounds in#108.Show files processed by nbstripout filterGit hasno builtin supportfor
listing files a clean or smudge filter operates on. As a workaround, change the
setup of your filter in.git/config,~/.gitconfigor$(prefix)/etc/gitconfigas follows to see the filenames either filter operates
on:[filter "nbstripout"]
    clean  = "f() { echo >&2 \"clean: nbstripout $1\"; nbstripout; }; f %f"
    smudge = "f() { echo >&2 \"smudge: cat $1\"; cat; }; f %f"
    required = true