{"id":525,"library":"jupyter-client","title":"Jupyter Client","description":"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.","status":"active","version":"8.8.0","language":"python","source_language":"en","source_url":"https://github.com/jupyter/jupyter_client","tags":["jupyter","kernel","protocol","client","asynchronous","messaging"],"install":[{"cmd":"pip install jupyter-client","lang":"bash","label":"Install jupyter-client"}],"dependencies":[{"reason":"Essential for the Jupyter messaging protocol, providing Python bindings for ZeroMQ networking.","package":"pyzmq"},{"reason":"A foundational package for Jupyter projects, providing core utilities.","package":"jupyter_core"},{"reason":"Jupyter's declarative configuration system, used throughout the client.","package":"traitlets"},{"reason":"A Python web framework and asynchronous networking library, integrated for event loop management.","package":"tornado"},{"reason":"Provides extensions to the standard Python `datetime` module, used for date serialization in messages.","package":"python-dateutil"},{"reason":"Patches asyncio to allow nested event loops, crucial for embedding Jupyter clients in certain environments.","package":"nest-asyncio"}],"imports":[{"symbol":"KernelManager","correct":"from jupyter_client import KernelManager"},{"symbol":"AsyncKernelManager","correct":"from jupyter_client.manager import AsyncKernelManager"},{"symbol":"BlockingKernelClient","correct":"from jupyter_client.blocking import BlockingKernelClient"},{"symbol":"find_connection_file","correct":"from jupyter_client import find_connection_file"}],"quickstart":{"code":"import time\nfrom jupyter_client import KernelManager\nfrom queue import Empty\n\ndef main():\n    # Start a Python kernel\n    km = KernelManager(kernel_name='python3')\n    km.start_kernel()\n\n    # Get a blocking client to interact with the kernel\n    kc = km.client(blocking=True)\n    kc.start_channels()\n\n    try:\n        # Ensure the client is connected and ready\n        kc.wait_for_ready(timeout=60)\n\n        # Execute some code\n        code = 'print(\"Hello from Jupyter Kernel!\")\\na = 10\\nprint(f\"a is {a}\")'\n        msg_id = kc.execute(code)\n\n        # Process IOPub messages until execution state is idle or timeout\n        while True:\n            try:\n                msg = kc.get_iopub_msg(timeout=1)\n                msg_type = msg['msg_type']\n                content = msg['content']\n\n                if msg_type == 'stream' and content['name'] == 'stdout':\n                    print(f\"[Kernel Output]: {content['text'].strip()}\")\n                elif msg_type == 'status' and content['execution_state'] == 'idle':\n                    print(\"[Kernel Status]: Idle\")\n                    break\n            except Empty:\n                # No messages in queue, continue waiting for idle status\n                continue\n            except Exception as e:\n                print(f\"Error receiving IOPub message: {e}\")\n                break\n\n    finally:\n        # Clean up: stop channels and shut down the kernel\n        kc.stop_channels()\n        km.shutdown_kernel()\n        print(\"Kernel shutdown complete.\")\n\nif __name__ == '__main__':\n    main()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"7.0.0 and later"},{"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`.","message":"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.","severity":"breaking","affected_versions":"7.0.0 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T14:39:35.498Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"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>)\"`.","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.","error":"ModuleNotFoundError: No module named 'jupyter_client'"},{"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.","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.","error":"Jupyter Notebook / Lab: Kernel connection failed / Kernel died / Kernel keeps restarting"},{"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`.","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).","error":"ImportError: cannot import name 'AsyncKernelManager' from 'jupyter_client'"},{"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>`.","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.","error":"NoSuchKernel: No such kernel named <kernel_name>"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.59,"mem_mb":11.9,"disk_size":"31.2M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.44,"mem_mb":11.9,"disk_size":"28M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.78,"mem_mb":13,"disk_size":"34.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.54,"mem_mb":13,"disk_size":"32M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.84,"mem_mb":13,"disk_size":"26.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.82,"mem_mb":13,"disk_size":"23M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.94,"mem_mb":13.5,"disk_size":"25.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.67,"mem_mb":13.5,"disk_size":"23M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.35,"mem_mb":10.6,"disk_size":"31.0M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":10.6,"disk_size":"28M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}