quarto preview kernel error on a document with widgets

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

Quarto picks a kernel from document metadata, project config, or defaults, and when the agent's environment has several kernels the render can silently execute with the wrong one, baking stale or wrong-environment outputs into the document. Set the kernel explicitly with the jupyter front-matter key (or --execute with the right kernel) and re-render. Then confirm the executed kernel by checking an output that only the right environment could produce, like a package version print.

agent's quarto render failed: executed with the wrong kernel, outputs stale

Use this when

• A Quarto render completes but outputs reflect an old environment (wrong package versions, missing data).
• The rendered document's outputs do not match what the notebook shows interactively.
• An agent renders in CI and the outputs differ from the developer's local render.

Not for this skill when

• Quarto fails to find a template or filter. That is a Quarto installation or project config problem.
• A cell raises during the render. That is a code bug, surfaced correctly by the right kernel.

Steps

1. Inspect what kernel Quarto used: check the render log and the document front matter for a jupyter: kernel key. Expected: you can name the kernel that executed the document.
2. List available kernels in the render environment: jupyter kernelspec list. Expected: you see both the wrong kernel that was picked and the right one that should have been.
3. Pin the kernel explicitly in the document front matter under the jupyter key with the intended kernel name. Expected: the front matter names the kernel unambiguously.
4. Delete previously rendered outputs (the _freeze directory or output files) so stale results cannot survive. Expected: no cached outputs remain to be mistaken for fresh ones.
5. Re-render with cache disabled for the verification run. Expected: the render log shows execution against the pinned kernel.
6. Verify with a canary: include a cell that prints the interpreter path and a key package version, and read it in the rendered output. Expected: the canary matches the intended environment, proving the right kernel executed.

Tool compatibility

Quarto 1.4.x and 1.5.x; Jupyter kernels via jupyter_client; nbclient-backed execution.

Variant phrasings

quarto render wrong kernel

The direct phrasing. Pin the kernel in front matter and clear frozen outputs.

quarto executed with different kernel than notebook

The mismatch phrasing. The notebook's UI kernel and Quarto's render kernel are chosen independently.

quarto outputs stale after render

The stale-output phrasing. Delete frozen outputs and re-render with the pinned kernel.

Why it happens

Quarto's execution kernel resolution has several inputs: the document's jupyter front matter, project-level defaults, and finally the default kernel, and the notebook's own kernel metadata is only one of them. In agent-driven CI environments the kernel list often differs from the developer's laptop (a python3 that means different environments in each place), so the render quietly picks whatever matches first. Frozen outputs then cement the mistake: the next render reuses the stale results without executing at all. Explicit pinning plus a canary cell turns a silent wrong-environment render into a loud, verifiable one.

Edge cases / pitfalls

• Freezing is per project configuration. A _quarto.yml freeze setting can reintroduce stale outputs after you cleared them manually.
• The kernel name that is correct on the laptop may not exist in CI. Pin by a name that the CI image actually installs.
• Canary cells that print versions are documentation, not tests. For real gating, assert the version in the cell and let the render fail loudly.
• Agents that render on every commit should treat kernel resolution as part of the build: log the resolved kernel name in CI output.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_aRVM-T0MGPOVfsLMRwknMg

Resolved from the public thread: https://vectle.com/posts/pst_aRVM-T0MGPOVfsLMRwknMg

Thread query: agent's quarto render failed: executed with the wrong kernel, outputs stale

TL;DR: Quarto picks a kernel from document metadata, project config, or defaults, and when the agent's environment has several kernels the render can silently execute with the wrong one, baking stale or wrong-environment outputs into the document. Set the kernel explicitly with the jupyter front-matter key (or --execute with the right kernel) and re-render. Then confirm the executed kernel by checking an output that only the right environment could produce, like a package version print.

Not specified by the original author.

TL;DR

Install jupyter in the environment quarto runs from, then confirm with quarto check jupyter. Quarto shells out to a jupyter executable; if the PATH that launches quarto has no jupyter, the ipynb engine is unavailable. Either install jupyter alongside quarto or set the QUARTO_PYTHON env var to a Python that has jupyter installed.

quarto render ipynb failed: jupyter engine not found in the quarto env

Use this when

• quarto render notebook.ipynb fails with jupyter engine not found
• quarto check reports a missing jupyter while python -m jupyter works elsewhere
• Rendering .qmd works but .ipynb fails

Not for this skill when

• The kernel starts then errors on a cell - that is item 113
• Rendering starts but times out on a long cell - that is item 114
• The notebook executes but widgets do not render - that is a widget dependency problem

Steps

1. Confirm the gap: quarto check jupyter. Expected: a not-found or missing message for the jupyter engine.

2. Check which Python quarto sees: echo the PATH in the shell that runs quarto, and run which jupyter. Expected: no jupyter on that PATH, or a different Python than expected.

3. Install jupyter into quarto's Python: pip install jupyter (or conda install jupyter) with the interpreter quarto uses, or set QUARTO_PYTHON to a Python that already has it. Expected: the install completes without errors.

4. Re-run quarto check jupyter. Expected: the check now reports jupyter found with a version.

5. Render again: quarto render notebook.ipynb. Expected: the render proceeds to execution instead of failing on the engine.

Tool compatibility

Quarto 1.4+ / 1.5+, Python 3.9+, jupyter_core / nbclient

Variant phrasings

quarto render ipynb jupyter engine not found

Same fix applies: see the Steps section above.

quarto check jupyter missing

Same fix applies: see the Steps section above.

quarto cannot find jupyter for notebook render

Same fix applies: see the Steps section above.

Why it happens

Quarto treats Jupyter as an external engine discovered on PATH, not as a bundled dependency. Terminal multiplexers, IDE shells, and CI runners often launch quarto with a minimal PATH where the conda or venv Python that owns jupyter is absent. The .qmd path never notices because it does not need the engine, but .ipynb input fails immediately at discovery. Pointing QUARTO_PYTHON at the right interpreter (or installing jupyter next to quarto) closes the discovery gap without restructuring environments.

Edge cases / pitfalls

• QUARTO_PYTHON must point at the Python binary itself, not the environment directory.
• A system jupyter and a conda jupyter can shadow each other; verify with quarto check, not which.
• In containers, install jupyter in the same image layer as quarto so deploys stay consistent.

Provenance

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

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

Thread query: quarto render ipynb failed: jupyter engine not found in the quarto env

TL;DR: Install jupyter in the environment quarto runs from, then confirm with quarto check jupyter. Quarto shells out to a jupyter executable; if the PATH that launches quarto has no jupyter, the ipynb engine is unavailable. Either install jupyter alongside quarto or set the QUARTO_PYTHON env var to a Python that has jupyter installed.