Getting started

This document describes some of the basics of installing and running the Jupyter Kernel Gateway.


Using pip

We make stable releases of the kernel gateway to PyPI. You can use pip to install the latest version along with its dependencies.

# install from pypi
pip install jupyter_kernel_gateway

Using conda

You can install the kernel gateway using conda as well.

conda install -c conda-forge jupyter_kernel_gateway


Once installed, you can use the jupyter CLI to run the server.

# run it with default options
jupyter kernelgateway

For example, if we define an endpoint in a notebook ./my_example.ipynb as follows:

# GET /hello/world

import json
import requests
import numpy as np

req = json.loads(REQUEST)
res = dict(data=np.random.randn(5, 4).tolist(), request=req)

and then run the gateway in http-mode and point specifically at that notebook, we should see some information printed in the logs:

jupyter kernelgateway --KernelGatewayApp.api=kernel_gateway.notebook_http --KernelGatewayApp.seed_uri=./my_example.ipynb --port=10100
[KernelGatewayApp] Kernel started: 12ac2daa-c62a-47e4-964a-336734557656
[KernelGatewayApp] Registering resource: /hello/world, methods: (['GET'])
[KernelGatewayApp] Registering resource: /_api/spec/swagger.json, methods: (GET)
[KernelGatewayApp] Jupyter Kernel Gateway at

We can curl against these endpoints to demonstrate it is working:

{"data": [[0.25854873480479607, -0.7997878409880017, 1.1136688704814672, -1.3292395513862103], [1.9879386172897555, 0.43368279132553395, -0.8623363198491706, -0.1571285171759644], [0.4437134294167942, 1.1323758620715763, 1.7350545168735723, -0.7617257690860397], [-0.4219717996309759, 0.2912776236488964, -0.21468140988270742, -0.8286216351049279], [0.5754812112421828, -2.042429681534432, 2.992678912690803, -0.7231031350239057]], "request": {"body": "", "args": {}, "path": {}, "headers": {"Host": "", "User-Agent": "curl/7.68.0", "Accept": "*/*"}}}

and the swagger spec:

{"swagger": "2.0", "paths": {"/hello/world": {"get": {"responses": {"200": {"description": "Success"}}}}}, "info": {"version": "0.0.0", "title": "my_example"}}

You can also run in the default websocket-mode:

jupyter kernelgateway --KernelGatewayApp.api=kernel_gateway.jupyter_websocket --port=10100
[KernelGatewayApp] Jupyter Kernel Gateway at

and again notice the output in the logs. This time we didn’t point to a specific notebook but you can test against the kernelspecs endpoint or the swagger endpoint:

{"default": "python3", "kernelspecs": {"python38364bit38conda21f48c44b19044fba5c7aa244072a647": {"name": "python38364bit38conda21f48c44b19044fba5c7aa244072a647", ...

For more details running-mode sections websocket-mode and http-mode.

NOTE: Watch out for notebooks that run things on import as this might cause the gateway server to crash immediately and the log messages are not always obvious.

Running using a docker-stacks image

You can add the kernel gateway to any docker-stacks image by writing a Dockerfile patterned after the following example:

# start from the jupyter image with R, Python, and Scala (Apache Toree) kernels pre-installed
FROM jupyter/all-spark-notebook

# install the kernel gateway
RUN pip install jupyter_kernel_gateway

# run kernel gateway on container start, not notebook server
CMD ["jupyter", "kernelgateway", "--KernelGatewayApp.ip=", "--KernelGatewayApp.port=8888"]

You can then build and run it.

docker build -t my/kernel-gateway .
docker run -it --rm -p 8888:8888 my/kernel-gateway