Jupyter Client (`jupyter_client`) provides the reference implementation of the Jupyter protocol, offering Python APIs for starting, managing, and communicating with Jupyter kernels. It also includes the `jupyter kernelspec` entrypoint for installing kernel specifications. Currently at version 8.8.0, the library maintains an active development pace with several releases annually to introduce enhancements and bug fixes.
pip install jupyter-clientVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to programmatically start a Jupyter kernel, execute Python code, and capture its output using `jupyter_client`'s blocking API. It initializes a `KernelManager`, obtains a `BlockingKernelClient`, and sends code for execution, then processes the incoming messages until the kernel returns to an idle state. Remember to call `stop_channels()` and `shutdown_kernel()` for proper cleanup.
Review the `Migration Guide` in the official documentation for detailed changes if you have custom `KernelManager` or `AsyncKernelManager` subclasses. Adjust method signatures and logic according to the new API.
For asynchronous operations, remove the `block=True` argument and ensure proper `await` calls within an `asyncio` event loop. For blocking behavior, use `jupyter_client.blocking.BlockingKernelClient`.
Implement explicit loops to fetch messages with appropriate timeouts (`get_iopub_msg(timeout=...)`) and handle `queue.Empty` exceptions. Continuously poll until an 'idle' status message is received or a specific reply is confirmed. Refer to the quickstart example for a basic pattern.
Always ensure that `kc.stop_channels()` and `km.shutdown_kernel()` are called, preferably within a `finally` block or context manager, to guarantee proper resource cleanup.
Ensure the desired kernel is installed and its kernel spec is registered with Jupyter. For Python kernels, this typically involves installing `ipykernel` (`pip install ipykernel`) and running `python -m ipykernel install --user --name <kernel_name>`. Verify `jupyter kernelspec list` shows the expected kernel. If custom kernel locations are used, check the `JUPYTER_PATH` environment variable.
Ensure the desired kernel is installed and registered. For Python kernels, this usually involves `ipykernel` installation and registration: `pip install ipykernel` followed by `python -m ipykernel install --user --name=my_kernel_name --display-name='My Kernel Display Name'`. Verify the kernel spec with `jupyter kernelspec list` to confirm it's recognized.
Install `jupyter-client` using pip or conda in the correct environment (e.g., `pip install jupyter_client` or `conda install jupyter_client`), and ensure Jupyter is launched from or configured to use that environment. If using a specific virtual environment, register the kernel using `python -m ipykernel install --user --name <env_name> --display-name "Python (<env_name>)"`.
First, try restarting the kernel (Kernel -> Restart). If the issue persists, verify the `argv` path in the `kernel.json` file (located via `jupyter kernelspec list`) points to the correct Python executable. Consider downgrading or upgrading `tornado` (e.g., `pip install tornado==5.1.1` or to the latest) or `pyzmq` (e.g., `pip install pyzmq==19.0.2`). Also, ensure no user-created Python files in your working directory (e.g., 'random.py', 'constants.py') conflict with standard library modules.
Upgrade `jupyter_client` and potentially other related Jupyter packages (`jupyter_core`, `ipykernel`, `notebook`, `jupyterlab`) to their latest compatible versions using a command like `pip install --upgrade jupyter_client jupyter_core ipykernel notebook jupyterlab`.
Install the kernel for the desired Python environment using `python -m ipykernel install --user --name <your_env_name> --display-name "Python (<your_env_name>)"`. Verify installed kernels with `jupyter kernelspec list` and ensure the name matches the one being requested. If a kernel spec is corrupted or points to an old environment, it might need to be manually edited or removed using `jupyter kernelspec remove <kernel_name>`.