nbclient "Kernel didn't respond" startup timeout in CI

By Kaveh Alemi·Latchkey

When nbclient starts a kernel it waits for the kernel to report ready within a startup_timeout. On slow or heavily loaded CI runners the kernel can take longer than the default to come up, and nbclient aborts with "Kernel didn't respond".

What this error means

A notebook run fails early with "RuntimeError: Kernel didn't respond in 60 seconds" before any cell executes, typically on a cold or busy runner.

RuntimeError: Kernel didn't respond in 60 seconds

Common causes

Slow kernel startup on a loaded runner

Heavy imports in the kernel's startup or a busy CPU make the kernel take longer than startup_timeout to signal readiness.

A misconfigured or partially-installed kernel

A kernelspec that points at a broken interpreter never reports ready, so the wait times out.

How to fix it

Raise the kernel startup timeout

Give the kernel more time to become ready on slower CI hardware.

jupyter nbconvert --to notebook --execute \
  --ExecutePreprocessor.startup_timeout=180 notebook.ipynb

Verify the kernel actually starts

1. Run jupyter kernelspec list to confirm the kernel is registered.
2. Start the kernel interpreter directly to ensure it imports cleanly.
3. Fix any broken kernelspec interpreter path before re-running.

jupyter kernelspec list

How to prevent it

• Set a generous startup_timeout for CI runners.
• Keep kernel startup imports light.
• Validate the kernelspec interpreter is healthy in setup.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation