Getting started

Install and first run

You need two things: the darkpyonix binary, which is the CLI and the manager, and a Python 3.8 or newer interpreter for the kernel. The interpreter does not need DarkPyonix installed.

Get the CLI

The CLI and the manager are one Rust binary, darkpyonix. It carries the kernel's Python sources inside it and unpacks them into ~/.darkpyonix/runtime/ on first use, so the binary alone is enough to run kernels.

Prebuilt binaries are not published yet planned. The plan is a wheel that carries the binary (INTENT D10). Until then, build it from a checkout. This needs a stable Rust toolchain.

git clone https://github.com/DarkPyonix/darkpyonix
cd darkpyonix
cargo build --release --manifest-path darkpyonix/manager/Cargo.toml
# the binary: darkpyonix/manager/target/release/darkpyonix

Put darkpyonix/manager/target/release/darkpyonix on your PATH.

The runtime API

Inside a kernel, import darkpyonix always works, because the kernel loads its own sources as darkpyonix. You install the package only to run a notebook outside a kernel, for example with python train.py in CI.

uv add darkpyonix                         # into a uv project
ppp core add "darkpyonix==0.2.0"          # with pypackpack
tcl install darkpyonix                    # with toolchain-lite

Choose the interpreter

A kernel runs on the interpreter chosen when it starts, in this order: --python PATH, then the DARKPYONIX_PYTHON environment variable, then python3 or python on PATH. The kernel keeps that interpreter until it is shut down, so --python matters only when the kernel is not running yet.

Point it at your project's environment so your code finds its packages:

uv sync                                   # .venv with your project's own dependencies
darkpyonix run train.py --python .venv/bin/python
darkpyonix run train.py --param lr=0.02   # second run: same kernel, new parameter

A first run

Any .py file works. A file with # %% cell markers gets per-cell outputs and per-cell run logs (see Notebook files).

The first run finds no manager, starts an ephemeral one, and the manager starts the kernel. The second run reuses both. If the first run is still going, the second is refused with exit code 75 and a hint to use --queue or stop. That is deliberate: two runs of one file in one process would share and corrupt state.

Afterwards the file has a sibling folder __runs__/train.py/ with one .ipynb per run. Run logs explains it.

Where things are kept

Per-user state lives in ~/.darkpyonix/. Set DARKPYONIX_HOME to move it, for example in tests.