nbstripout Documentation

repository·main·Indexed 23 days ago

A utility for stripping output and metadata from Jupyter, IPython, and Zeppelin notebooks. It is primarily used as a Git filter or pre-commit hook to reduce diff noise and repository size by ensuring only code and markdown are tracked in version control.

Tokens: 5.6K
Snippets: 15
Records: 27
Agent score: 81%

What's inside nbstripout

Overview of nbstripout
main
What is nbstripout?
nbstripout is a utility that reads a Jupyter or IPython notebook from a file or stdin, strips the output and certain metadata, and writes the cleaned version back to the original file or to stdout.
Primary Use Case
It is designed to be used as a Git filter or a pre-commit hook. This allows you to keep notebook outputs in your local files for viewing in a notebook UI, while ensuring that only the code and markdown are tracked in Git. This practice:
- Minimizes Git diffs
- Reduces repository file size
https://github.com/kynan/nbstripout/blob/main/README.md
How to keep output for specific cells or notebooks
main
You can prevent nbstripout from stripping output for specific parts of a notebook using metadata or tags.
For Specific Cells
1. Tags: Add the keep_output tag to the cell using the Jupyter Tags toolbar.
2. Metadata: Set the following in the cell's metadata:
  { "keep_output": true }
For Entire Notebooks Add the same metadata to the notebook-level metadata:
```
{ "keep_output": true }
```
Note on Initialization Cells nbstripout automatically preserves output for cells marked as initialization cells:
```
{ "init_cell": true }
```
```
{
  "keep_output": true,
}

{
  "init_cell": true,
}
```
https://github.com/kynan/nbstripout/blob/main/README.md
Use nbstripout CLI to strip notebook output
main
You can use the nbstripout command to strip output from IPython, Jupyter, or Zeppelin notebooks. By default, this modifies the file in-place.
Basic Usage
```
nbstripout FILE.ipynb [FILE2.ipynb ...]
nbstripout FILE.zpln
```
Advanced CLI Options
- Force non-.ipynb extensions: Use -f to process files that don't end in .ipynb.
- Zeppelin mode: Use -m zeppelin -f <file.ext> to process Zeppelin files with other extensions.
- Stdout/Pipelines: Use -t to write to stdout instead of modifying in-place, allowing use in shell pipelines.
- Dry run: Use --dry-run to list files that would be stripped without modifying them.
- Verification: Use --verify to perform a dry run that fails if any files would have been stripped.
- Recursive processing: Use find to process all notebooks in a directory tree:
  find . -name '*.ipynb' -exec nbstripout {} +
```
nbstripout FILE.ipynb [FILE2.ipynb ...]
nbstripout FILE.zpln

nbstripout -f FILE.ipynb.bak

nbstripout -m zeppelin -f <file.ext>

cat FILE.ipynb | nbstripout > OUT.ipynb

nbstripout -t FILE.ipynb | other-command

nbstripout --dry-run FILE.ipynb

nbstripout --verify FILE.ipynb

find . -name '*.ipynb' -exec nbstripout {} +
```
https://github.com/kynan/nbstripout/blob/main/README.md
Install nbstripout as a Git filter
main
You can automate output stripping by setting up nbstripout as a Git filter. This ensures notebooks are stripped automatically during Git operations.
Installation Scopes
- Per-repository: Run nbstripout --install. This modifies .git/config and .git/info/attributes.
- Global (User-wide): Run nbstripout --install --global. This applies to all your repositories. It is recommended to also specify a global attributes file: nbstripout --install --global --attributes=~/.config/git/attributes.
- System-wide: Run sudo nbstripout --install --system. This applies to all users on the machine.
Customizing Python Path If your Python interpreter is in a non-standard location, specify it during installation: nbstripout --install --python python3
Uninstallation Use the --uninstall flag with the same scope used during installation (e.g., --global, --system, or --attributes=.gitattributes).
Checking Status
- nbstripout --is-installed: Exits with 0 if installed in the current repo, 1 otherwise.
- nbstripout --status: Prints installation status and configuration summary.
```
nbstripout --install
nbstripout --install --attributes .gitattributes
nbstripout --install --python python3
nbstripout --install --global
[sudo] nbstripout --install --system

nbstripout --uninstall
nbstripout --uninstall --global
[sudo] nbstripout --uninstall --system
nbstripout --uninstall --attributes .gitattributes

nbstripout --is-installed
nbstripout --status
```
https://github.com/kynan/nbstripout/blob/main/README.md

Guard notebooks with the nbstripout GitHub Action

main

Use the kynan/nbstripout GitHub Action to verify that notebooks are properly stripped of output in your CI/CD pipeline. This action runs nbstripout --verify, which performs a non-destructive dry-run check. If any notebook contains output that should be stripped, the action fails.

Action Inputs

Input	Description	Default
`python-version`	Python version to use (supports versions, ranges, or "3.x")	`'3.x'`
`paths`	Newline-separated list of paths to check (supports wildcards)	`'*/.ipynb'`
`extra-keys`	Extra metadata keys to strip (space-separated)	`''`
`keep-output`	Keep output in notebooks	`'false'`
`keep-count`	Keep execution counts	`'false'`
`strip-init-cells`	Strip init cells	`'false'`

Basic Usage Example

name: Check Notebooks Output

on:
  pull_request:
    paths:
      - '**.ipynb'
  push:
    branches:
      - main
    paths:
      - '**.ipynb'
  workflow_dispatch:

jobs:
  check-notebooks:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v6
      
      - name: Check notebooks are stripped
        uses: kynan/nbstripout@main
        with:
          paths: '**/*.ipynb'

name: Check Notebooks Output

on:
  pull_request:
    paths:
      - '**.ipynb'
  push:
    branches:
      - main
    paths:
      - '**.ipynb'
  workflow_dispatch:

jobs:
  check-notebooks:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v6
      
      - name: Check notebooks are stripped
        uses: kynan/nbstripout@main
        with:
          paths: '**/*.ipynb'

Install nbstripout via conda
main
If you are using the Anaconda distribution, you can install nbstripout from the conda-forge channel using the conda package manager:
```
conda install -c conda-forge nbstripout
```
https://github.com/kynan/nbstripout/blob/main/README.md
Install nbstripout via pip
main
To install or upgrade to the latest version of nbstripout using the Python package index (PyPI), use the following command:
```
pip install --upgrade nbstripout
```
https://github.com/kynan/nbstripout/blob/main/README.md
Exclude files and folders from Git filters
main
If you want to prevent nbstripout from processing certain files or directories, you can use .gitattributes or .git/info/attributes.
Excluding a Directory To disable the filter for everything in a docs folder: docs/** filter= diff=
Excluding a Specific File notebooks/Analysis.ipynb filter= diff=
Verification You can check which attributes are applied to a file using: git check-attr -a -- path/to/file
```
docs/** filter= diff=
notebooks/Analysis.ipynb filter= diff=

git check-attr -a -- path/to/file
```
https://github.com/kynan/nbstripout/blob/main/README.md
Install nbstripout as a manual Git filter
main
To set up nbstripout as a git filter and diff driver, run the following commands in your repository. Replace /path/to/nbstripout with the actual path to the nbstripout executable.
To install for the current repository only:
```
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'
```
To install globally (for your user across all repositories), add the --global flag to the commands above.
To install system-wide (for all users), add the --system flag to the commands above.
After configuring git, you must tell git which files to use the filter on. Create a .gitattributes file (to version it with the repo) or edit .git/info/attributes (for the current repo only) with these lines:
```
*.ipynb filter=nbstripout
*.ipynb diff=ipynb
```
For global attributes, add those lines to ~/.config/git/attributes or $(prefix)/etc/gitattributes.
```
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'
```
https://github.com/kynan/nbstripout/blob/main/README.md
Install nbstripout for Python 2.7
main
As of version 0.4.0, nbstripout supports Python 3 only. If your environment requires Python 2.7, you must install version 0.3.10:
```
pip install nbstripout==0.3.10
```
https://github.com/kynan/nbstripout/blob/main/README.md
Use nbstripout with pre-commit
main
You can use nbstripout as a pre-commit hook to automatically strip .ipynb files before they are committed.
Warning: In this mode, nbstripout modifies your working copy. This differs from the Git filter mode, which only modifies what Git sees during commit/diff.
Add the following to your .pre-commit-config.yaml:
```
repos:
- repo: https://github.com/kynan/nbstripout
  rev: 0.9.1
  hooks:
    - id: nbstripout
```
Then run pre-commit install to activate it.
If you need to pass arguments with spaces (like --extra-keys), you must quote them as a whole within the args list.
```
repos:
- repo: https://github.com/kynan/nbstripout
  rev: 0.9.1
  hooks:
    - id: nbstripout
```
https://github.com/kynan/nbstripout/blob/main/README.md
Debug: Show files processed by nbstripout filter
main
Since Git does not natively support listing files processed by a clean/smudge filter, you can use a wrapper function in your Git config to print the filenames to stderr.
Update your .git/config, ~/.gitconfig, or $(prefix)/etc/gitconfig with the following configuration:
```
[filter "nbstripout"]
    clean  = "f() { echo >&2 \"clean: nbstripout $1\"; nbstripout; }; f %f"
    smudge = "f() { echo >&2 \"smudge: cat $1\"; cat; }; f %f"
    required = true
```
```
[filter "nbstripout"]
    clean  = "f() { echo >&2 \"clean: nbstripout $1\"; nbstripout; }; f %f"
    smudge = "f() { echo >&2 \"smudge: cat $1\"; cat; }; f %f"
    required = true
```
https://github.com/kynan/nbstripout/blob/main/README.md

nbstripout Documentation

What's inside nbstripout

What is nbstripout?

Primary Use Case

Action Inputs

Basic Usage Example