Jupyter HTTP-over-WebSocket

0.0.8 · active · verified Thu Apr 16

Jupyter HTTP-over-WebSocket is a Jupyter server extension (version 0.0.8) maintained by the Google Colaboratory team. It enables Jupyter notebooks to proxy HTTP traffic over WebSockets, which is crucial for bypassing browser-imposed cross-domain HTTP restrictions when connecting to a localhost Jupyter server. The project has a low release cadence, with the last update in March 2020.

Common errors

```
Receiving 403 errors when attempting connection
```
cause The authentication cookie required by the Jupyter server for allowing requests is not present or has expired in the browser attempting to connect.

fix Ensure you open the URL provided by the Jupyter server (e.g., `http://localhost:8888/?token=...`) in the browser you are using to connect from. Using the `--no-browser` flag and manually navigating to this URL helps guarantee the cookie is set. An incognito window can resolve issues caused by browser extensions.
```
[E 13:43:13.400 NotebookApp] Support for specifying --pylab on the command line has been removed. [E 13:43:13.400 NotebookApp] Please use %pylab jupyter_http_over_ws or %matplotlib jupyter_http_over_ws in the notebook itself.
```
cause This error, while not directly from `jupyter-http-over-ws`, indicates an outdated or misconfigured Jupyter environment where `--pylab` is used as a command-line argument. This flag has been removed from newer Jupyter versions.

fix Do not use `--pylab` on the command line when starting Jupyter Notebook. If you need `pylab` or `matplotlib` integration, use the magic commands (`%pylab` or `%matplotlib`) directly within your Jupyter notebook cells. Ensure your Jupyter installation is up-to-date.

Warnings

gotcha When connecting to a local Jupyter runtime, you must ensure the browser window specified in the command-line (or the one showing the authentication URL) is opened. This action sets an authentication cookie required for subsequent requests, preventing 403 Forbidden errors.
Fix: After starting the Jupyter server, copy the authentication URL printed in the terminal and paste it into the browser you intend to use for connection. Using `--no-browser` flag and opening the link manually is recommended. If issues persist, try an incognito window to rule out browser extension conflicts.
breaking Starting Jupyter Notebook with `--NotebookApp.allow_origin` allows cross-domain communication. While necessary for this extension's functionality, it can pose security risks if the origin is not explicitly trusted. By connecting to a local runtime, you allow the frontend to execute arbitrary code and access local resources.
Fix: Only allow connections from trusted origins (e.g., `https://colab.research.google.com`). Always ensure you trust the authors of any notebook you execute and understand the code's implications on your local machine. Refer to Jupyter's security documentation for more details.

Install

pip install jupyter_http_over_ws Install the package
jupyter serverextension enable --py jupyter_http_over_ws Enable the Jupyter server extension

Quickstart

This quickstart installs the necessary package, enables the server extension, and starts a Jupyter Notebook server configured to allow connections from a specified origin (e.g., Google Colab) via HTTP-over-WebSocket. The `--no-browser` flag is recommended to manually open the authentication URL in your preferred browser, ensuring the necessary auth cookie is set.

pip install jupyter_http_over_ws
jupyter serverextension enable --py jupyter_http_over_ws

# Start Jupyter Notebook with an allowed origin for WebSocket proxying
jupyter notebook \
    --NotebookApp.allow_origin='https://colab.research.google.com' \
    --port=8888 \
    --no-browser

# Note: Open the URL printed in the terminal from your browser to authenticate and set cookies.

view raw JSON →