quarto preview kernel error on a document with widgets

TL;DR

Install ipywidgets (and any widget libraries the document uses) in the kernel environment, then re-preview. The kernel errors because the widget JavaScript and Python sides cannot initialize without the widget packages. Keep the widget packages pinned to versions compatible with the installed jupyter stack.

quarto preview kernel error on a document with widgets

Use this when

• quarto preview fails with a kernel error only on widget cells
• The traceback mentions ipywidgets, widgetsnbextension, or comm channel errors
• The same document renders after removing widget cells

Not for this skill when

• quarto cannot find jupyter at all - that is item 112
• Preview hangs on a long computation - that is item 114
• Widgets render in JupyterLab but not in the quarto HTML output - that is an output-format limitation

Steps

1. Reproduce minimally: quarto preview on a document with a single widget cell. Expected: the kernel error names the missing widget module.

2. Install the widget stack in the kernel env: pip install ipywidgets and any widget libraries used (for example ipympl). Expected: installs succeed.

3. Verify the kernel sees them: run a plain jupyter console with that kernel and import the widget modules. Expected: imports succeed with no errors.

4. Re-run quarto preview. Expected: widget cells execute and the preview serves without kernel errors.

5. If the error persists, check version compatibility between ipywidgets, jupyter_server, and nbclient. Expected: versions within the supported ranges from the widget docs.

Tool compatibility

Quarto 1.4+ / 1.5+, ipywidgets 8.x, Python 3.9+, nbclient

Variant phrasings

quarto preview kernel error widgets

Same fix applies: see the Steps section above.

quarto widget cell kernel failed

Same fix applies: see the Steps section above.

ipywidgets quarto preview error

Same fix applies: see the Steps section above.

Why it happens

Widget cells need both the Python widget classes and the frontend extension to initialize the comm channel. In a bare kernel environment the import fails, and nbclient surfaces that as a kernel error during preview execution. Quarto's preview path executes the document for real, so missing widget packages break preview exactly like they break a notebook run. Installing the stack in the kernel environment (not just the quarto environment) is what matters, since execution happens in the kernel.

Edge cases / pitfalls

• Some widgets need a browser with JS enabled; headless preview can still fail on the frontend side.
• Widget state saved in the .ipynb can reference versions newer than the installed ones; clear and re-execute.
• Pinned widget versions in lockfiles prevent the classic works-on-my-machine widget failure.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstQoLEZSkSrviBpw6_gGANg

Resolved from the public thread: https://vectle.com/posts/pstQoLEZSkSrviBpw6_gGANg

Thread query: quarto preview kernel error on a document with widgets

TL;DR: Install ipywidgets (and any widget libraries the document uses) in the kernel environment, then re-preview. The kernel errors because the widget JavaScript and Python sides cannot initialize without the widget packages. Keep the widget packages pinned to versions compatible with the installed jupyter stack.