Concepts#

conda-ship separates three concerns:

  • resolving and recording a conda runtime package set

  • stamping a generic runtime template into a distribution-specific runtime

  • staging release artifacts that downstream projects can distribute

The split from conda-express makes that separation explicit. conda-ship owns these generic concerns; conda-express owns the cx and cxz distribution built with them.

Builder#

The cs CLI is the builder. It reads conda.toml/conda.lock, pyproject.toml with [tool.conda] plus conda.lock, the compatible pixi.toml/pixi.lock pair, or pyproject.toml with [tool.pixi] plus pixi.lock, applies [tool.conda-ship], then derives a runtime lock, bundle files, runtimes, and artifact metadata.

The selected source lockfile is the source of the concrete conda package records. conda-ship is not a replacement for conda-workspaces, Pixi, or any other workspace solver; it consumes a solved environment and turns it into runtime artifacts.

Runtime#

A runtime is the executable that users run after conda-ship finishes. Examples include demo, demoz, cx, and cxz.

The runtime name is the base executable name for that runtime. It can come from [tool.conda-ship].runtime or --runtime, and it is not a conda environment name. The embedded layout adds the z suffix to the staged executable name because that variant contains compressed package archives.

Use “runtime” for the executable conda-ship produces, “delegate” for the executable inside the managed prefix that receives pass-through arguments, and “artifact” for the release files written to dist/.

Runtime Template#

cs-template is an internal generic binary target. It is not a first-party distribution. During cs build, the builder copies a generic runtime template under the resolved runtime name and stamps the copy with the runtime name, delegate, install scheme, install name, metadata filename, environment variable names, runtime lock, and optional bundle. The stamped copy is the runtime. Released builds and packaged local builds use prebuilt template assets.

Runtime Lock#

The runtime lock is derived from the configured source environment, then filtered through [tool.conda-ship].exclude. conda-ship stamps the derived lock into every runtime artifact and stages a copy next to the output binary. It is not a second checked-in project lockfile.

cs inspect derives the same runtime lock without writing files, so it is the local preflight command. cs build and cs run derive the lock as part of their normal work.

The generated runtime can install from:

  • the stamped lockfile and network package downloads

  • the stamped lockfile and an external package bundle

  • the stamped lockfile and an embedded package bundle

Bundles#

Bundles contain downloaded conda package archives. They are not conda channel mirrors; conda-ship already has the channel and package records in the runtime lock.

The external layout pairs a runtime with RUNTIME.bundle.tar.zst. The embedded layout appends z to the runtime name and includes the compressed bundle inside the runtime.

An embedded runtime automatically uses its bundled archives during bootstrap. An explicit --bundle can still override that bundle.

The bundle format is intentionally narrow. conda-ship writes top-level .conda and .tar.bz2 files, then verifies them against the lockfile at install time. Embedded bundles reject nested paths and links before extraction.