Skip to main content

Strips outputs from Jupyter and IPython notebooks

Project description

nbstripout: strip output from Jupyter and IPython notebooks

Opens a notebook, strips its output, and writes the outputless version to the original file.

Useful mainly as a git filter or pre-commit hook for users who don’t want to track output in VCS.

This does mostly the same thing as the Clear All Output command in the notebook UI.

Based on


This screencast demonstrates the use and working principles behind the nbstripout utility and how to use it as a Git filter:


You can download and install the latest version of nbstripout from PyPI, the Python package index, as follows:

pip install --upgrade nbstripout

When using the Anaconda Python distribution, install nbstripout via the conda package manager from conda-forge:

conda install -c conda-forge nbstripout


Strip output from IPython / Jupyter notebook (modifies the files in-place):

nbstripout FILE.ipynb [FILE2.ipynb ...]

Force processing of non .ipynb files:

nbstripout -f FILE.ipynb.bak

Write to stdout e.g. to use as part of a shell pipeline:

cat FILE.ipynb | nbstripout > OUT.ipynb


nbstripout -t FILE.ipynb | other-command

Set up the git filter and attributes as described in the manual installation instructions below:

nbstripout --install

Set up the git filter using .gitattributes

nbstripout --install --attributes .gitattributes

Set up the git filter in your global ~/.gitconfig

nbstripout --install --global

Remove the git filter and attributes:

nbstripout --uninstall

Remove the git filter from your global ~/.gitconfig and attributes

nbstripout --install --global

Remove the git filter and attributes from .gitattributes:

nbstripout --uninstall --attributes .gitattributes

Check if nbstripout is installed in the current repository (exits with code 0 if installed, 1 otherwise):

nbstripout --is-installed

Print status of nbstripout installation in the current repository and configuration summary of filter and attributes if installed (exits with code 0 if installed, 1 otherwise):

nbstripout --status

Print the version:

nbstripout --version

Show this help page:

nbstripout --help

Configuration files

The following table shows in which files the nbstripout filter and attribute configuration is written to for given extra flags to --install and --uninstall:













--global --attributes=.gitattributes



Install globally

Usually, nbstripout is installed per repository so you can choose where to use it or not. You can choose to set the attributes in .gitattributes and 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 install nbstripout for 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/attributes

This will set up the filters and diff driver in your ~/.gitconfig and instruct git to apply them to any .ipynb file in any repository.

Note that you need to uninstall with the same flags:

nbstripout --uninstall --global --attributes=~/.config/git/attributes

Apply retroactively

nbstripout can be used to rewrite an existing Git repository using git filter-branch to strip output from existing notebooks. This invocation uses --index-filter and 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 with git 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 "{}" +'

Keeping some output

Do not strip the execution count/prompt number

nbstripout --keep-count

Do not strip the output

nbstripout --keep-output

To mark special cells so that the output is not striped, set the "keep_output": true metadata 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,

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 the init_cell nbextension.

Stripping metadata

This is configurable via git config (--global) filter.nbstripout.extrakeys. An example would be:

git config --global filter.nbstripout.extrakeys '
  metadata.celltoolbar metadata.kernel_spec.display_name 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'

Excluding folders

To exclude a certain folder from being processed by the nbstripout filter, add the following line to your .git/info/attributes (or .gitattributes if you choose to use that):

docs/** filter= diff=

This will disable nbstripout for any file in the docs directory.

To check which attributes a given file has with the current config, run

git check-attr -a -- path/to/file

For 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: nbstripout

For 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 installation

Set 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/config file of the current repository.

If you want the filter to be installed globally for your user, add the --global flag to the git config invocations above to have the configuration written to your ~/.gitconfig and apply to all repositories.

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=ipynb

This instructs git to use the filter named _nbstripout_ and the diff driver named _ipynb_ set up in the git config above for every .ipynb file in the repository.

If you want the attributes be set for .ipynb files in any of your git repositories, add those two lines to ~/.config/git/attributes. Note that this file and the ~/.config/git directory may not exist.

Mercurial usage

Mercurial does not have the equivalent of smudge filters. One can use an encode/decode hook but this has some issues. An alternative solution is to provide a set of commands that first run nbstripout, then perform these operations. This is the approach of the mmf-setup package.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nbstripout-0.3.6.tar.gz (16.5 kB view hashes)

Uploaded Source

Built Distribution

nbstripout-0.3.6-py2.py3-none-any.whl (15.0 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page