kernelspec json references a python that no longer exists

TL;DR

The kernel.json hard-codes the absolute path of the Python that registered it, so deleting or renaming that environment leaves a spec pointing at nothing and the kernel fails to launch. Inspect the spec's argv with jupyter kernelspec list plus a read of kernel.json, then reinstall the spec from a working interpreter with python -m ipykernel install. If the environment still exists under a new path, editing argv to the new Python path is the faster fix.

kernelspec json references a python that no longer exists

Use this when

• Selecting the kernel produces a launch failure mentioning a missing executable or a bad interpreter path.
• jupyter kernelspec list finds the kernel, but starting it fails immediately with no kernel-side traceback.
• An old virtualenv or conda env was deleted or renamed and its kernel entry still lingers.

Not for this skill when

• The kernel is not listed at all. That is a search-path problem, a different fix.
• The kernel starts and then dies importing packages. That is an environment-content problem, not a dead interpreter path.

Steps

1. Find the spec directory: jupyter kernelspec list and note the path for the broken kernel. Expected: a directory path containing kernel.json.
2. Read kernel.json and look at the first entry of argv. Expected: an absolute Python path you can test in the next step.
3. Test the interpreter: run that exact path with --version (or ls the path). Expected: 'no such file' or equivalent, confirming the interpreter is gone.
4. Pick the replacement interpreter: the Python of the environment you actually want (a venv's bin/python or a conda env's python). Expected: that Python runs and import ipykernel succeeds in it.
5. Reinstall the spec from the live interpreter: [that-python] -m ipykernel install --user --name [kernel-name] --display-name "[display]". Expected: install output confirms the spec was written, and kernel.json argv now points at the live Python.
6. If the environment merely moved, you may instead edit kernel.json argv[0] to the new path and restart the server. Expected: the kernel launches without reinstalling.
7. Launch the kernel from the UI or with jupyter console --kernel [kernel-name]. Expected: a working REPL prompt, proving the spec resolves.

Tool compatibility

ipykernel 6.x, jupyterclient 7.x/8.x, jupytercore 5.x; venv, virtualenv, and conda-managed interpreters.

Variant phrasings

kernel failed to start: no such file or directory python

The launch-error phrasing of the dead-interpreter problem. Check kernel.json argv.

jupyter kernel points to deleted virtualenv

The venv-deletion phrasing. Reinstall the spec from the replacement interpreter.

kernel.json argv wrong python path

The direct phrasing. Either reinstall the spec or edit argv to the live path.

Why it happens

A kernelspec is a static JSON file, and ipykernel install bakes the installing interpreter's absolute path into argv at registration time. Nothing watches the filesystem afterwards, so when the environment is deleted, renamed, or moved, the spec keeps pointing at the old path indefinitely. Kernel startup then fails at process spawn, before any Python code runs, which is why there is no Python traceback to debug. Reinstalling from a live interpreter regenerates the spec with a valid path, and it also refreshes the display name and metadata in one step.

Edge cases / pitfalls

• Reinstalling with the system Python when you meant the project venv creates a spec that launches fine but lacks your packages. Always run the install command with the intended interpreter.
• Editing kernel.json by hand is quick but brittle: a JSON syntax slip breaks the whole spec. Validate with python -m json.tool kernel.json after editing.
• Old specs with the same name in another data directory can shadow your fixed one. Re-check jupyter kernelspec list paths after the fix.
• Agents that recreate environments on every run should reinstall the kernelspec as part of environment setup, not as a one-time manual step.

Provenance

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