Jupyter Client

raw JSON →
8.8.0 verified Tue May 12 auth: no python install: verified quickstart: stale

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-client

Common errors

error ModuleNotFoundError: No module named 'jupyter_client' ↓
cause The `jupyter_client` package is not installed in the Python environment where Jupyter is trying to run, or the environment is not correctly activated or selected.
fix
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>)".
error Jupyter Notebook / Lab: Kernel connection failed / Kernel died / Kernel keeps restarting ↓
cause This broad issue can be caused by various factors, including corrupted or misconfigured kernel specifications (kernel.json), incompatible `pyzmq` or `tornado` package versions, insufficient memory, or conflicts with user-created Python scripts shadowing standard library modules.
fix
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.
error ImportError: cannot import name 'AsyncKernelManager' from 'jupyter_client' ↓
cause This error typically indicates a version incompatibility between `jupyter_client` and other Jupyter components or dependent libraries. The API for `AsyncKernelManager` might have changed, or an older version of `jupyter_client` is being used with newer components (or vice-versa).
fix
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.
error NoSuchKernel: No such kernel named <kernel_name> ↓
cause Jupyter cannot find the kernel specification for the requested kernel name. This can happen if the kernel was never installed, was removed, or its `kernel.json` file is misconfigured or located in an incorrect path.
fix
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>.

Warnings

breaking Jupyter Client 7.0 introduced significant internal API changes for `KernelManager` and `AsyncKernelManager`. Methods like `pre_start_kernel`, `_launch_kernel`, `_kill_kernel`, and `finish_shutdown` had their signatures or return types altered. While primarily affecting subclasses, these changes can impact custom kernel managers. ↓
fix 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.
breaking With Jupyter Client 7.0, `AsyncKernelClient` methods (e.g., `get_shell_msg`, `get_iopub_msg`, `get_stdin_msg`, `get_control_msg`) no longer accept the `block: bool = True` keyword argument. These methods are now purely asynchronous. ↓
fix 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`.
gotcha Reliably receiving all messages from a kernel, especially output streams (IOPub), can be challenging. Developers often miss messages or get stuck in infinite loops if message processing and timeout handling are not robustly implemented. ↓
fix 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.
gotcha Improper management of kernel lifecycles can lead to zombie processes, leaked resources, or stale connection files. Failing to shut down kernels and stop client channels can consume system resources. ↓
fix 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.
gotcha The `jupyter_client.kernelspec.NoSuchKernel` error indicates that the requested kernel (e.g., 'python3') cannot be found or accessed by Jupyter. This often happens if the kernel is not installed, the kernel specification files are missing, or the `JUPYTER_PATH` environment variable is not configured correctly. ↓
fix 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.
gotcha The `jupyter_client.kernelspec.NoSuchKernel` error indicates that the requested kernel (e.g., 'python3', 'ir') could not be found or is not properly registered with Jupyter. This typically happens when the kernel is not installed or its specification files are missing or inaccessible to `jupyter_client`. ↓
fix 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 compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk
3.10 alpine (musl) - - 0.59s 31.2M
3.10 slim (glibc) - - 0.44s 28M
3.11 alpine (musl) - - 0.78s 34.7M
3.11 slim (glibc) - - 0.54s 32M
3.12 alpine (musl) - - 0.84s 26.2M
3.12 slim (glibc) - - 0.82s 23M
3.13 alpine (musl) - - 0.94s 25.8M
3.13 slim (glibc) - - 0.67s 23M
3.9 alpine (musl) - - 0.35s 31.0M
3.9 slim (glibc) - - 0.46s 28M

Imports

Quickstart stale last tested: 2026-04-23

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.

import time
from jupyter_client import KernelManager
from queue import Empty

def main():
    # Start a Python kernel
    km = KernelManager(kernel_name='python3')
    km.start_kernel()

    # Get a blocking client to interact with the kernel
    kc = km.client(blocking=True)
    kc.start_channels()

    try:
        # Ensure the client is connected and ready
        kc.wait_for_ready(timeout=60)

        # Execute some code
        code = 'print("Hello from Jupyter Kernel!")\na = 10\nprint(f"a is {a}")'
        msg_id = kc.execute(code)

        # Process IOPub messages until execution state is idle or timeout
        while True:
            try:
                msg = kc.get_iopub_msg(timeout=1)
                msg_type = msg['msg_type']
                content = msg['content']

                if msg_type == 'stream' and content['name'] == 'stdout':
                    print(f"[Kernel Output]: {content['text'].strip()}")
                elif msg_type == 'status' and content['execution_state'] == 'idle':
                    print("[Kernel Status]: Idle")
                    break
            except Empty:
                # No messages in queue, continue waiting for idle status
                continue
            except Exception as e:
                print(f"Error receiving IOPub message: {e}")
                break

    finally:
        # Clean up: stop channels and shut down the kernel
        kc.stop_channels()
        km.shutdown_kernel()
        print("Kernel shutdown complete.")

if __name__ == '__main__':
    main()
last verified Tue May 12
next check Fri Jun 26