Jupyter notebook kernel not found: NoSuchKernel, ipykernel install (tested)

Kernel not found (or NoSuchKernel: No such kernel named X) means the notebook's metadata names a kernel that isn't registered on this machine. Check jupyter kernelspec list, then register your environment with python -m ipykernel install --user --name X or switch the notebook to an existing kernel.

1. Reproduce: a notebook that names a kernel this machine doesn't have

A notebook stores the kernel it wants in its metadata ("kernelspec": {"name": "myproject"}). run.sh creates such a notebook on a machine that only has the default python3 kernel, then fixes it two ways. JUPYTER_DATA_DIR points into the test folder so --user installs land there instead of ~/.local/share/jupyter.

cd /tmp/jk408
export JUPYTER_DATA_DIR=/tmp/jk408/data PATH=/tmp/jn408/ve/bin:$PATH
python - <<'PY'
import json
nb = {"cells": [{"cell_type": "code", "execution_count": None, "id": "a1", "metadata": {}, "outputs": [], "source": ["import sys; print(sys.prefix)"]}],
      "metadata": {"kernelspec": {"name": "myproject", "display_name": "Python (myproject)", "language": "python"}}, "nbformat": 4, "nbformat_minor": 5}
json.dump(nb, open("nb.ipynb", "w"))
PY
echo '$ jupyter kernelspec list'
jupyter kernelspec list
echo '$ jupyter nbconvert --to notebook --execute nb.ipynb   # notebook asks for kernel "myproject"'
jupyter nbconvert --to notebook --execute nb.ipynb 2>&1 | tail -1
echo
echo '$ python -m ipykernel install --user --name myproject --display-name "Python (myproject)"'
python -m ipykernel install --user --name myproject --display-name "Python (myproject)"
echo '$ jupyter kernelspec list'
jupyter kernelspec list
echo '$ jupyter nbconvert --to notebook --execute --stdout nb.ipynb | grep -A1 text'
jupyter nbconvert --to notebook --execute --stdout nb.ipynb 2>/dev/null | grep -A1 '"text"'
echo
echo '$ jupyter nbconvert --execute --ExecutePreprocessor.kernel_name=python3 ...   # override instead'
rm -rf data/kernels/myproject
jupyter nbconvert --to notebook --execute --ExecutePreprocessor.kernel_name=python3 --stdout nb.ipynb 2>/dev/null | grep -A1 '"text"'
echo '$ jupyter kernelspec remove -y myproject'
python -m ipykernel install --user --name myproject >/dev/null 2>&1
jupyter kernelspec remove -y myproject

Output (jupyter_core 5.9.1, nbconvert 7.17.2, ipykernel, Python 3.13 on Linux):

$ jupyter kernelspec list
Available kernels:
  python3    /tmp/jn408/ve/share/jupyter/kernels/python3
$ jupyter nbconvert --to notebook --execute nb.ipynb   # notebook asks for kernel "myproject"
jupyter_client.kernelspec.NoSuchKernel: No such kernel named myproject

$ python -m ipykernel install --user --name myproject --display-name "Python (myproject)"
Installed kernelspec myproject in /tmp/jk408/data/kernels/myproject
$ jupyter kernelspec list
Available kernels:
  python3      /tmp/jn408/ve/share/jupyter/kernels/python3
  myproject    /tmp/jk408/data/kernels/myproject
$ jupyter nbconvert --to notebook --execute --stdout nb.ipynb | grep -A1 text
     "text": [
      "/tmp/jn408/ve\n"

$ jupyter nbconvert --execute --ExecutePreprocessor.kernel_name=python3 ...   # override instead
     "text": [
      "/tmp/jn408/ve\n"
$ jupyter kernelspec remove -y myproject
Removed /tmp/jk408/data/kernels/myproject

• jupyter kernelspec list shows which kernels exist. The notebook wanted myproject, which wasn't listed, so executing it failed with NoSuchKernel: No such kernel named myproject.
• Fix 1, register the environment as a kernel: run python -m ipykernel install --user --name myproject with the Python of the environment you want (activate it first, or use its full path). The generated kernel.json stores that interpreter's full path (here /tmp/jn408/ve/bin/python), so the kernel keeps using that environment no matter where Jupyter itself runs.
• Fix 2, use another kernel: pick an existing kernel in the UI (Kernel → Change kernel), or on the command line pass --ExecutePreprocessor.kernel_name=python3.
• Remove a stale kernel with jupyter kernelspec remove -y NAME. A kernel whose environment was deleted still appears in kernelspec list; in a separate test, executing with such a kernel failed with FileNotFoundError: [Errno 2] No such file or directory naming the missing Python path.

2. Checklist

1. jupyter kernelspec list: is the notebook's kernel name there?
2. Not there: activate the project env, pip install ipykernel, python -m ipykernel install --user --name NAME.
3. There but won't start: open its kernel.json and check the Python path in argv still exists; if not, remove and reinstall the kernelspec.

Related: Jupyter "Error Starting Kernel", jupyter nbconvert is not installed, plotly requires nbformat.

Written with AI assistance. Measured on 2026-10-23 with jupyter_core 5.9.1, nbconvert 7.17.2 and ipykernel from PyPI, Python 3.13 on Linux. The script ran verbatim and the output was pasted unedited. PlainTables is our extension; Jupyter is free.