IForth (Python package)

Forth kernel for Jupyter notebook / lab. This is a fork of github.com/jdfreder/iforth.

Open in Colab

Note: Check the changelog to see the latest changes in development as well as in releases.

Do check out this video where Andrew McKewan used IForth jupyter kernel as part of his presentation at Silicon Valley Forth Group (SVFIG) in August 2026: Finances in Forth

Installation

Pre-Requisite: Install jupyter & gforth, ensuring they are available in the environment PATH.

After installing via either of the 2 methods mentioned below (using uv or pip), verify by running jupyter kernelspec list that forth kernel is listed.

Note: Currently supported on Linux only because on Windows, gforth doesn't work. Has not been tested on Mac OS.

Install using uv python package manager

TODO: this way isn't tested, only pip install way has been tested.

$ uv tool install forth_kernel
$ uv tool run forth_kernel.self_install --user     # Register IForth Jupyter kernel

Install using pip

$ pip install forth_kernel
$ python -m forth_kernel.self_install --user      # Register IForth Jupyter kernel

Running

Run Jupyter Notebook / Lab as usual, just select IForth Jupyter kernel for the Jupyter Notebook.

Debugging Logs are written at ~/.jupyter/forth_kernel.log .

Contribution & Development Install

See CONTRIBUTING.md .

Notes for Repo Maintainers

See MAINTAINERS.md .

Documentation

See detailed documentation at this repo's wiki. TODO: The wiki is empty, update docs there!

Also see this proposed talk presentation on IForth for implementation details of this Jupyter kernel.

Usage

• Run jupyter notebook (or jupyter lab, whichever you prefer).
• In a new or existing notebook, use the kernel selector (located at the top right of the notebook) to select IForth.

Known Limitations

• Output containing ok or compiled: the kernel detects when GForth has finished a line by watching for its ok / compiled prompt. Forth code whose own output ends with those words — e.g. ." ok" — can be mistaken for the prompt, truncating the rest of that line's output.
• Words that read from stdin (KEY, ACCEPT, REFILL) are not supported: the kernel provides no way to send input to a running word.
• QUIT isn't handled: Since QUIT does no output we can't detect when a line is complete so the cell just hangs in the running state.

Misc Notes

Jupyter Kernel Architecture

Jupyter is essentially a front-end that communicates with a computation server via a protocol (aptly called the Jupyter protocol). This computation server is called a kernel. All jupyter needs to know about a kernel is which ports to use to communicate different kinds of messages.

The Jupyter stack looks like this:

• JupyterLab / Notebook frontend (browser): Renders notebooks, lets you edit cells, handles user events.
• Jupyter server (Python): Manages files, launches kernels, proxies messages.
• Kernel (language backend): Actually executes your code.

The frontend and the kernel do not share memory. They talk over five distinct logical channels, each responsible for a specific type of message exchange:

• Shell: The main request/reply loop. The frontend sends code execution requests here.
• IOPub: A broadcast channel. The kernel publishes “side effects” here, such as stdout, stderr, and renderable data (plots, HTML).
• Stdin: Allows the kernel to request input from the user (e.g., when a script asks for a password).
• Control: A high-priority channel for system commands (like “Shutdown” or “Interrupt”) that must bypass the execution queue.
• Heartbeat: A simple ping/pong socket to ensure the kernel is still alive.

Jupyter Registration Spec

Jupyter discovers kernels via a JSON specification file (kernel.json). You can list these with jupyter kernelspec list.

When Jupyter starts a kernel, it generates a connection file (represented by {connection_file} in the args above). This ephemeral JSON file tells the kernel which ports to bind to for the five channels:

{  
  "shell_port": 41083,  
  "iopub_port": 42347,  
  "stdin_port": 56773,  
  "control_port": 57347,  
  "hb_port": 34681,  
  "ip": "127.0.0.1",  
  "key": "aa072f60-5cac0ac2506b1a572678209a",  
  "transport": "tcp",  
  "signature_scheme": "hmac-sha256",  
  "kernel_name": "IForth"  
}

Some notable fields:

• Ports: One per channel (shell_port, iopub_port, etc.).
• Key + signature_scheme: Used to sign messages (HMAC) so rogue processes can’t spoof messages.
• Transport + IP: Usually TCP over localhost, but in principle could be remote.

Each of these ports is used to send different types of payloads to the kernel. So any implementation of the Jupyter protocol needs to handle these messages correctly (or at least, gracefully).