Most Jupyter kernel problems are really environment-identity problems
| What you see | What to prove |
|---|---|
| Your virtual environment is not listed as a kernel | Whether ipykernel is installed and that environment has a registered kernelspec |
| The notebook opens but imports fail | Whether the notebook kernel uses the same Python where the package was installed |
| You selected a kernel but it starts and dies | The kernelspec executable path and whether that Python still exists/starts |
| Jupyter and VS Code show different Python environments | Which executable each frontend is actually launching |
Start by identifying the Python you actually want Jupyter to use
Activate the intended virtualenv or conda environment, then run:
python -c "import sys; print(sys.executable)"Copy that path. It is your reference point. If you are not inside the intended environment, stop here and activate/select the correct one before registering a kernel.
Check whether that environment has ipykernel
python -m pip show ipykernelIf it is missing and this is the environment you want notebooks to execute in, install it into that same Python environment:
python -m pip install ipykernelThis changes the environment by installing a package, so do it only after confirming the executable above.
Register a kernel with a name you can recognize
IPython documents registering kernels separately when you want a different Python version, virtualenv or conda environment available to Jupyter.
python -m ipykernel install --user --name myenv --display-name "Python (myenv)"Replace myenv with a stable short name. The --display-name is what you will see in Jupyter's kernel picker. Reusing the same internal --name can overwrite an existing kernelspec, so choose deliberately.
If a kernel is already listed but points to the wrong Python
List registered kernels:
jupyter kernelspec listOpen the relevant kernelspec's kernel.json and inspect the first executable in its argv array. It should point to a Python that still exists and matches the environment you intend to run.
Verify inside the notebook, not only in the terminal
After selecting the kernel, run this in a notebook cell:
import sys
print(sys.executable)The path should match the intended environment. Then test the package that originally failed. If pip install succeeded in one terminal but the notebook still raises ModuleNotFoundError, the notebook is probably using a different Python.
If the kernel starts and immediately dies
- Run the kernelspec's Python executable directly from a terminal.
- Check whether the environment was deleted, moved or partially upgraded.
- Reinstall/repair
ipykernelinside that exact environment if Python itself starts normally. - Start Jupyter again and select the newly registered kernel.
Verify the repair
- The intended kernel appears in Jupyter's kernel list.
- A notebook using that kernel prints the expected
sys.executable. - The package that previously failed imports from the same environment.
- Closing and reopening Jupyter does not switch the notebook back to a stale kernel.
Related Python environment checks
Frequently asked questions
Why does Jupyter not show my virtual environment?
The environment usually needs ipykernel installed and a kernelspec registered for Jupyter to offer it as a selectable kernel.
Why can pip say a package is installed while Jupyter cannot import it?
pip may be installing into a different Python environment from the notebook kernel. Compare the notebook sys.executable with the Python used for installation.
What is the difference between --name and --display-name in ipykernel install?
The name is the internal kernelspec identifier; the display name is the human-readable label shown in Jupyter menus.
Sources and review notes
Troubleshooting order was reviewed against IPython: Installing the IPython kernel · Jupyter: kernel migration/background. Hardware, driver and menu names can vary by PC, accessory and Windows build.