How to Test Notebooks With nbmake and papermill in CI

nbmake runs each notebook top to bottom under pytest and fails if any cell raises, catching rot early.

Use pytest --nbmake to execute notebooks as tests, or papermill to run a parameterized notebook and fail on error.

Steps

• Install nbmake (and papermill if you parameterize).
• Run pytest --nbmake notebooks/ to execute every notebook.
• For parameter sweeps, run papermill in.ipynb out.ipynb -p date 2026-06-30.

Workflow

steps:
  - uses: actions/checkout@v4
  - run: pip install nbmake papermill pytest
  - name: Execute notebooks
    run: pytest --nbmake --nbmake-timeout=300 notebooks/
  - name: Parameterized run
    run: papermill notebooks/report.ipynb /tmp/out.ipynb -p run_date 2026-06-30

Gotchas

• Set --nbmake-timeout so a hung cell fails instead of running to the job limit.
• Strip output and secrets from committed notebooks so diffs stay clean.

Related guides