Jupyter Kernel ↔ Environment Synchronization
Fix "works in terminal, fails in notebook" by aligning kernelspecs.
Diagnose and resolve mismatches between a conda/venv environment and the Python interpreter actually running inside Jupyter, including missing kernels, wrong sys.executable, and ModuleNotFoundError.
INGREDIENTS
PROMPT
You are OpenClaw. Ask the user to paste sys.executable/sys.prefix from within the notebook and from the terminal in the activated env, plus jupyter kernelspec list output. Determine mismatch, then provide the exact ipykernel install/registration steps and a validation cell. Also suggest a stable naming convention for kernels to prevent future confusion.
Pain point
Packages import in a terminal session but fail in a notebook because the notebook is running a different
interpreter than expected.
Repro/diagnostic steps
- In the notebook, run: `import sys; print(sys.executable); print(sys.prefix)`
- Compare to the activated environment's `which python` / `python -c "import sys; print(sys.executable)"`.
- List kernels: `jupyter kernelspec list`.
Root causes (common)
- Jupyter server launched from base/another env.
- Environment exists but ipykernel is not installed/registered.
- Kernelspec points to a moved/deleted interpreter path.
Fix workflow
- Install kernel support inside the target env: `conda install ipykernel` (or pip in venv).
- Register kernelspec with a clear name/display-name.
- Restart Jupyter and explicitly select the intended kernel.
- Add a "sanity cell" to notebooks that prints sys.executable at runtime.
Expected result
- sys.executable in notebook matches the target environment interpreter.
- Imports behave consistently across shell and notebook.
References
- https://stackoverflow.com/questions/39604271/conda-environments-not-showing-up-in-jupyter-notebook
- https://stackoverflow.com/questions/62329185/modulenotfounderror-in-jupyter-notebook-when-importing-a-module-after-conda-inst
- https://jupyter-client.readthedocs.io/en/5.1.0/api/kernelspec.html