Build A Runtime With A Custom Delegate

This tutorial builds a runtime whose configured delegate is python instead of conda.

The managed prefix only needs Python and its dependencies. conda-ship does not require conda, conda-rattler-solver, or conda-spawn when the distribution does not use them.

Before You Start

Install conda-ship and either conda-workspaces or Pixi:

conda-workspaces

conda install --name base -c conda-forge conda-pypi
conda create -n cs-python-demo -c conda-forge python pip conda-workspaces
conda activate cs-python-demo
conda pypi install conda-ship

Pixi

conda install --name base -c conda-forge conda-pypi
conda create -n cs-python-demo -c conda-forge python pip pixi
conda activate cs-python-demo
conda pypi install conda-ship

If you prefer not to install conda-pypi into base, use python -m pip install conda-ship in the activated environment instead.

Create The Project

Create a project directory:

mkdir python-runtime
cd python-runtime

conda-workspaces

conda workspace init --format conda --name python-runtime
conda workspace add --feature ship --no-lockfile-update \
  "python>=3.12"

Add conda-ship policy:

cat >> conda.toml <<'TOML'

[tool.conda-ship]
runtime-name = "pydemo"
runtime-version = "0.1.0"
delegate-executable = "python"
artifact-layout = "online"
source-environment = "ship"
TOML

Lock it:

conda workspace lock

Pixi

pixi init --channel conda-forge
cat >> pixi.toml <<'TOML'

[feature.ship.dependencies]

[environments]
ship = { features = ["ship"], no-default-feature = true }

[tool.conda-ship]
runtime-name = "pydemo"
runtime-version = "0.1.0"
delegate-executable = "python"
artifact-layout = "online"
source-environment = "ship"
TOML
pixi add --feature ship --no-install \
  "python>=3.12"
pixi lock

Build It

Run a preflight, then build:

cs inspect
cs build

The runtime is staged as dist/pydemo on Unix and dist/pydemo.exe on Windows.

Choose A Temporary Prefix

Create a temporary parent directory for the tutorial prefix:

mkdir -p .tmp

Run Python Through The Runtime

Create a small script:

cat > hello.py <<'PY'
import sys

print("hello from", sys.executable)
PY

Run it through the runtime:

PYDEMO_PREFIX="$PWD/.tmp/pydemo" ./dist/pydemo hello.py

On the first invocation, pydemo automatically installs the selected Python environment into the managed prefix and then passes hello.py unchanged to the Python executable. Later invocations reuse that prefix.

Clean Up

Remove the tutorial install path:

rm -rf -- "$PWD/.tmp/pydemo"

What You Learned

The delegate-executable is the executable that receives every argument after the runtime is automatically bootstrapped. Use delegate-executable = "conda" for conda-like distributions, and another executable when the runtime should provide fewer or different commands. The selected source environment only needs to include that delegate and its runtime dependencies.