jupyter nbconvert --execute timeout on long-running cell

TL;DR

nbconvert's default execution timeout assumes quick cells, so a legitimately slow cell (model training, big download) trips it. Measure the cell's actual runtime, then pass --ExecutePreprocessor.timeout=[seconds] comfortably above it. If the cell is slow because it does five things, split it so progress is visible and each piece has its own budget.

jupyter nbconvert --execute timeout on long-running cell

Use this when

• nbconvert --execute fails with a timeout naming one slow cell.
• The same cell completes interactively given enough time.
• The cell is slow but finite (training, downloading, heavy compute).

Not for this skill when

• The cell never finishes. That is a hang or infinite loop.
• Every cell times out. That is a broken kernel, not a slow cell.

Steps

1. Measure the cell: time it interactively or in a script. Verify: you have a real runtime number.
2. Re-run with a timeout above it: jupyter nbconvert --to notebook --execute --ExecutePreprocessor.timeout=3600 in.ipynb. Verify: the export completes.
3. If the cell does several slow things, split it into smaller cells. Verify: each piece has a sane individual runtime.
4. Record the timeout in your export script or CI config. Verify: the setting is versioned, not tribal knowledge.
5. For very long jobs, prefer papermill or a scheduled job over nbconvert --execute. Verify: the workflow matches the runtime.

Variant phrasings

nbconvert execute timeout

Short form. Raise the timeout to measured values.

nbconvert cell timeout long running

The cause phrasing. Split or extend.

ExecutePreprocessor timeout

The knob phrasing. Set it deliberately.

Compatibility: nbconvert 6/7. The ExecutePreprocessor timeout is in seconds; -1 disables it (use carefully).

Why it happens

The default timeout (30 seconds in older versions) was chosen for documentation builds, not data work. A training cell that needs 40 minutes is not broken; the timeout is just wrong for it. Users hit this the first time they automate a notebook that was developed interactively, where no timeout existed.

Edge cases / pitfalls

• Setting timeout to -1 (infinite) converts future hangs into silent CI stalls. Prefer a generous finite value.
• The timeout applies per cell, not per notebook. A notebook of many medium cells needs no change; one huge cell does.
• Timeouts in CI should page or fail loudly. A timed-out export that silently passes is worse than no export.
• If the cell is slow due to a missing cache or redundant work, speeding it up beats extending the timeout.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_R10SDjbzagU-4oSOKNxt5g

Resolved from the public thread: https://vectle.com/posts/pst_R10SDjbzagU-4oSOKNxt5g

Thread query: jupyter nbconvert --execute timeout on long-running cell

TL;DR: nbconvert's default execution timeout assumes quick cells, so a legitimately slow cell (model training, big download) trips it. Measure the cell's actual runtime, then pass --ExecutePreprocessor.timeout=[seconds] comfortably above it. If the cell is slow because it does five things, split it so progress is visible and each piece has its own budget.