How Generated Runtimes Work#

When you run cs build, conda-ship copies the cs-template runtime template and writes your configuration, lockfile, and optional bundle into that copy. This step is called stamping. Set the runtime name with [tool.conda-ship].runtime-name or --runtime-name. Use [tool.conda-ship].artifact-name or --artifact-name when the staged executable needs a different filename.

What cs build Writes#

During a runtime build, conda-ship writes these details into the copied binary:

  • runtime name, artifact name, and delegate executable

  • install scheme and install name

  • installer, when configured

  • runtime lock

  • optional compressed package bundle

  • documentation URL

  • metadata filename

  • bundle and offline environment variable names

  • optional condarc contents and base-freezing setting

  • optional executable update source and build number

Where The Template Comes From#

The conda-ship package installs cs-template alongside cs. The GitHub Action downloads it from conda-ship’s release assets. Release asset names include the target platform, for example:

cs-template-x86_64-unknown-linux-gnu
cs-template-aarch64-apple-darwin
cs-template-x86_64-pc-windows-msvc.exe

Template selection uses this order:

  1. --template PATH

  2. CONDA_SHIP_TEMPLATE, when nonempty

  3. cs-template next to cs, when --target is omitted

When passing --target, also select a matching template with --template or CONDA_SHIP_TEMPLATE. The builder does not search PATH or download a template.

Running the template directly fails with a message that points back to cs build. The stamped copy contains the runtime name, lockfile, package metadata, and install settings needed to run.

Source checkouts use the same selection order. cs build does not compile a template automatically.

Keep Native Builders And Templates Paired#

macOS and Windows builders require the signed-layout reader declaration emitted by the matching cs-template release. conda-ship 0.9.0 rejects native templates from 0.8.0 and earlier. Upgrade cs and cs-template together instead of mixing release assets. Linux templates do not use this native declaration.

For the GitHub Action, update the pinned full action commit SHA and the conda-ship-version input together. For custom packaging, download the builder and template from the same release and verify both against that release’s attestations or SHA256SUMS.

What Users See#

The finished runtime does not expose conda-ship commands. On first invocation it installs the selected package set into its managed prefix, then executes the configured delegate with the original arguments. Later invocations execute the same delegate directly through the existing prefix.

When update configuration is stamped, the native runtime can check, stage, apply, and recover executable updates. It can also reconcile a replacement performed by an external package manager. The installed ownership and installation kind are recorded in the managed prefix, so the same stamped bytes can be directly or externally managed. This behavior is part of the stamped native template. The conda-ship Python package is not installed in the managed prefix and is not needed at runtime.

This means --help, --version, status, shell, uninstall, and every other argument belong to the delegate. For a conda delegate, conda info reports conda and prefix status. If the distribution includes a conda-spawn version that provides conda shell, users can run RUNTIME shell.

Downstream distributions can stamp native condarc contents and protect the base prefix with a CEP 22 frozen marker. Without those opt-ins, conda-ship leaves conda configuration and package-created frozen markers untouched.

What Each Project Chooses#

Some runtime behavior is visible to users:

  • automatic bootstrap before the first delegate invocation

  • unchanged delegate arguments, process streams, signals, and exit status

  • optional commands provided by packages such as conda-spawn and conda-self

  • bundle and offline variables derived from the runtime name

  • CONDA_SHIP_PREFIX and a runtime-specific prefix variable for names other than conda

  • optional executable update behavior selected by stamped configuration

The package set, runtime name, delegate, documentation URL, and release channel belong to the project using conda-ship.