Registry / web-framework / jupyter-kernel-gateway

jupyter-kernel-gateway

library3.0.1pypypiunverified

Jupyter Kernel Gateway is a web server for spawning and communicating with Jupyter kernels. It provides a REST API that allows execution of code in Jupyter Kernels and manages their lifecycle, often used to expose notebooks as RESTful APIs. The current version is 3.0.1, and the project maintains an active release cadence with several updates per year, now managed under the `jupyter-server` organization.

web-framework http-networking

pip install jupyter-kernel-gateway

github ↗package ↗

INSTALL

IMPORT

SIG · JUPYTER-KERNEL-GAT

jupyter-kernel-gateway

web-frameworkpythonv3.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

This quickstart demonstrates how to programmatically start the Jupyter Kernel Gateway server and make a simple API request to verify its operation. In typical use, Kernel Gateway is run directly from the command line using `jupyter kernelgateway`.

import subprocess import sys import time import requests # Start Kernel Gateway in a separate process print("Starting Jupyter Kernel Gateway on port 9999...") process = subprocess.Popen( [sys.executable, "-m", "jupyter_kernel_gateway.app", "--KernelGatewayApp.port=9999", "--KernelGatewayApp.ip=127.0.0.1", "--KernelGatewayApp.allow_origin='*'"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True ) # Give it a moment to start up time.sleep(5) try: # Verify it's running by hitting an endpoint print("Attempting to connect to Kernel Gateway...") response = requests.get("http://127.0.0.1:9999/api/kernelspecs") response.raise_for_status() print("Kernel Gateway is running and accessible. Available kernelspecs:") print(response.json()) except Exception as e: print(f"Error connecting to Kernel Gateway: {e}") if process.poll() is not None: stdout, stderr = process.communicate() print("Server stdout:\n", stdout) print("Server stderr:\n", stderr) finally: print("Stopping Kernel Gateway...") if process.poll() is None: # Check if still running process.terminate() process.wait(timeout=5) print("Kernel Gateway stopped.")

jupyter-kernel-gateway --version

Debug

Known issues

breakingStarting from v2.5.2, `jupyter-kernel-gateway` removed its internal dependency on `ipython_genutils`. Custom extensions or deployment scripts that relied on this module might break upon upgrade.

fix

Review custom code and remove any dependencies on `ipython_genutils` modules. Migrate to equivalent functionality in `traitlets` or standard Python libraries.

affects: >=2.5.2

gotchaVersions of `jupyter-kernel-gateway` prior to 3.0.0 were pinned to `jupyter-client < 8`. Users with a newer `jupyter-client` version in their environment might encounter dependency conflicts or unexpected behavior.

fix

Upgrade `jupyter-kernel-gateway` to version 3.0.0 or later, which has updated dependency requirements. Alternatively, ensure your `jupyter-client` version is compatible (e.g., `<8`) when using older `jupyter-kernel-gateway` versions.

affects: <3.0.0

gotchaWhen deploying `jupyter-kernel-gateway` as a public-facing service, critical security configuration like CORS origins (`--KernelGatewayApp.allow_origin`) and authentication must be explicitly set. Default settings are not secure for production environments.

fix

Always review and configure `KernelGatewayApp` settings, especially `ip`, `port`, `allow_origin`, and `auth_token` or other authentication mechanisms suitable for your deployment scenario. Consult the official documentation for comprehensive security guidelines.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'jupyter_kernel_gateway'

The `jupyter-kernel-gateway` package is either not installed in the active Python environment or the environment where it's installed is not the one being used.

fix

Ensure `jupyter_kernel_gateway` is installed in the correct environment by running: `pip install jupyter_kernel_gateway` or `python -m pip install jupyter_kernel_gateway` if within a notebook context.

Kernel refused to connect

This often occurs due to port conflicts, firewall restrictions preventing connections to the kernel gateway, or an incompatibility with the `tornado` package version that `jupyter-kernel-gateway` depends on.

fix

Check for other processes using port 8888 (the default for Kernel Gateway) and stop them, or specify a different port using `--KernelGatewayApp.port=<PORT>`. If `tornado` is the issue, downgrade it: `pip uninstall tornado` then `pip install tornado==5.1.1` (or a version compatible with your `jupyter-kernel-gateway` installation).

Error starting kernel: Invalid response: 503 Service Temporarily Unavailable

This error typically indicates that the Jupyter Kernel Gateway or the underlying kernel process is unable to start or respond to requests, often due to resource limitations, incorrect kernel specifications, or timeout issues when integrated with other services like JupyterHub or Enterprise Gateway.

fix

Review the Kernel Gateway logs for more specific errors. Increase resource allocations for kernels if running in a containerized environment (e.g., Kubernetes). Check kernel specifications (`jupyter kernelspec list`) and ensure they point to valid Python executables and dependencies. Adjust client-side timeouts (e.g., `GatewayClient.request_timeout`) if the kernels take a long time to start.

Forbidden

When accessing API endpoints like `/api/kernels` or `/api/kernelspecs`, a 'Forbidden' message indicates that the request lacks proper authentication or authorization, or the Kernel Gateway's configuration disallows the operation (e.g., listing kernels without explicit permission).

fix

Ensure that `jupyter kernelgateway` is started with appropriate authentication settings, such as `--KernelGatewayApp.token='YOUR_TOKEN'` or `--KernelGatewayApp.password='YOUR_PASSWORD'`. If listing kernels is desired, enable it explicitly with `--KernelGatewayApp.list_kernels=true`. For cross-origin requests, configure `--KernelGatewayApp.allow_origin='*'` or specific origins.

Upgrade

Version history

3.0.1latest on PyPI · released Mar 12, 2024

Audit

Dependencies

pythonrequiredRequires Python 3.8 or newer.

Agent activity

7 hits · last 30 days

node

Resources

githubhttp://github.com/jupyter-incubator/kernel_gateway ↗

packagehttps://pypi.org/project/jupyter-kernel-gateway/ ↗