quarto "Jupyter kernel ... not found" in CI

Quarto renders Python documents through the Jupyter engine, which needs jupyter and a kernel for the language. If the runner lacks jupyter or the requested kernel, Quarto fails when it tries to start the kernel for the document.

What this error means

quarto render fails with "ERROR: Unable to start the Jupyter kernel" or a message that the requested kernel was not found, often noting that jupyter is not installed.

quarto

ERROR: Unable to start the Jupyter kernel for the document.
No Jupyter kernel named 'python3' was found.

Common causes

jupyter is not installed for the render

Quarto's jupyter engine needs the jupyter package present; without it, no kernel can be started.

The requested kernel is not registered

The document's jupyter: kernel name has no matching kernelspec on the runner.

How to fix it

Install jupyter and ipykernel before rendering

Install jupyter and ipykernel into the render interpreter.
Register the python3 kernel.
Run quarto render after the kernel exists.

Terminal

python -m pip install jupyter ipykernel
python -m ipykernel install --user --name python3
quarto render report.qmd

Point the document at an installed kernel

Set the document's kernel to a name that jupyter kernelspec list shows.

report.qmd

---
title: Report
jupyter: python3
---

How to prevent it

Install jupyter and ipykernel in the same step as the Quarto render.
Match the document jupyter: kernel to a registered kernelspec.
Verify with jupyter kernelspec list before rendering.