ipymini

ipymini is a Jupyter kernel for Python with a Rust protocol engine, a small(ish), readable(ish) codebase, and strong IPython parity.

This was almost entirely implemented by AI, and no human currently fully understands all the generated code, so please be very careful, because we don't actually know what this code does. The AI closely referenced the ipykernel, xeus, xeus-python, and jupyter_kernel_test projects during development. So all credit for this project belongs to the authors of those packages, and to authors of the excellent documentation and specifications referred to (e.g DAP spec; JEPs; etc) - but of course all blame for mistakes is entirely our/AI's fault.

Having said all that, we have been working on this and testing it for ~6 months before making it public, and it is working well for our needs at least (Mac and Linux usage on nbclassic and Solveit). We have restructured it a number of times to make it more modular and understandable, and added a lot of tests of concurrency, complex workflows, etc.

What we’ve aimed to do

• Keep the Jupyter engine in Rust and Python language semantics in IPython.
• Match ipykernel behavior where it matters (IOPub ordering, message shapes, history, inspect, etc.).
• Use IPython instead of re‑implementing Python semantics.
• Expand protocol‑level tests (IOPub, interrupts, completions, etc.) to approach upstream parity.

Requirements

• Python 3.11+

Install

From PyPI:

pip install ipymini

The install puts a kernelspec in the environment. Jupyter from that environment lists it as the py kernel, with no separate install step. An editable install (pip install -e .) does the same, with a copy of kernel.json taken at install time.

Installing the kernel spec

An install already puts the kernelspec in its own environment. From a source checkout, the built-in installer copies the kernelspec into another Jupyter kernels directory. Install it for the current user:

python -m ipymini install --user

Or install into the current environment:

python -m ipymini install --sys-prefix

After either option, you should see it in:

jupyter kernelspec list

Alternatively, use the repo’s JUPYTER_PATH during development. Set JUPYTER_PATH to include the repo’s share/jupyter:

export JUPYTER_PATH=/path/to/ipymini/share/jupyter:$JUPYTER_PATH

Running manually

ipymini is a normal Jupyter kernel executable. It expects a connection file:

python -m ipymini -f /path/to/connection.json

(When run via Jupyter, that file is created and passed automatically.)

Concurrent execution helpers

Inside an ipymini cell, get_ipython().kernel.subshell() routes later execute requests from the same client session to a temporary subshell, while get_ipython().kernel.sidecar() uses the persistent kernel-wide sidecar:

with get_ipython().kernel.subshell():
    await something()

with get_ipython().kernel.sidecar():
    await something_reentrant()

The same helpers are also available as from ipymini import sidecar, subshell.

Configuring env and working directory

For per-launch configuration, rely on the kernel launcher:

• KernelManager: pass env and cwd to start_kernel(...).
• Kernelspec: add an "env" dict to share/jupyter/kernels/py/kernel.json for static defaults.

Example (KernelManager):

from jupyter_client import KernelManager

km = KernelManager(kernel_name="py")
km.start_kernel(env={"MY_FLAG": "1"}, cwd="/path/to/workdir")

Optional env flags:

• KERNMINI_IOPUB_QMAX: maximum number of queued IOPub events (default 10000).
• KERNMINI_HOLD_TIMEOUT: maximum time in seconds for an unreleased held execution (default 3600).
• KERNMINI_CELL_NAME: override the temporary debugger filename for a cell.
• IPYMINI_USE_JEDI: enable or disable IPython's Jedi completer.

On POSIX, ipymini isolates the kernel into its own process group and terminates that group as the last shutdown step, so user-created child processes are cleaned up with the kernel. Nested ipymini kernels started by KernelManager watch their parent pid and shut themselves down when that parent exits. Direct SIGTERM to the kernel uses the same cleanup path. Windows does not provide this process-group cleanup guarantee; after normal cleanup the kernel process exits with os._exit().

Developer guide

See DEV.md.