Manifests And Plugin Entry Points#

conda-ship supports conda-workspaces manifests and Pixi manifests.

conda-ship is not an environment manager. It consumes a solved conda environment and turns it into runtimes.

Manifest Priority#

conda-ship treats conda.toml as the preferred project manifest. The conda-workspaces pyproject.toml embedded form with [tool.conda] is also supported. pixi.toml and pyproject.toml with [tool.pixi] are supported when a downstream project already keeps its conda solve in Pixi.

Inside a build root, conda-ship looks for manifests in this order:

  1. conda.toml

  2. pixi.toml

  3. pyproject.toml when it contains [tool.conda] or [tool.pixi]

When conda.toml is selected, conda-ship reads package records from conda.lock. When pyproject.toml with [tool.conda] is selected, it also reads package records from conda.lock. When pixi.toml or pyproject.toml with [tool.pixi] is selected, it reads package records from pixi.lock. If a pyproject.toml contains both [tool.conda] and [tool.pixi], [tool.conda] wins.

The lockfile remains the source of concrete package records. If the selected lockfile is missing, create it with the tool that owns the manifest, then run cs inspect or cs build --dry-run again.

Source Environment Selection#

The solved environment used for the runtime is selected explicitly by [tool.conda-ship].source-environment:

[tool.conda-ship]
runtime = "demo"
delegate = "conda"
layout = "online"
source-environment = "ship"
exclude = ["conda-libmamba-solver"]
docs-url = "https://example.com/demo/"

If source-environment is omitted, conda-ship fails. That keeps release builds from accidentally packaging a default, development, or test environment.

conda-ship derives a runtime lock that contains only the selected source environment, renamed to default for the generated runtime. The derived lock is stamped into staged runtimes and copied into the staged artifact directory. It is build output, not another source project lockfile.

Conda Workspace Shape#

A conda-workspaces project puts conda intent in the conda-workspaces schema and conda-ship-specific build policy in [tool.conda-ship]:

[workspace]
name = "demo"
channels = ["conda-forge"]
platforms = ["linux-64", "osx-arm64", "win-64"]

[feature.ship.dependencies]
python = ">=3.12"
conda = ">=25.1"
conda-rattler-solver = "*"
conda-spawn = ">=0.1.0"

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

[tool.conda-ship]
runtime = "demo"
delegate = "conda"
layout = "online"
source-environment = "ship"
exclude = ["conda-libmamba-solver"]

[tool.conda-ship] is for conda-ship build behavior: which source environment to turn into a runtime, which packages to prune after the solve, artifact naming policy, bundle policy, and runtime documentation links.

Package and channel intent belongs in the conda workspace sections when that manifest is available. conda-ship reads the selected lockfile environment and stamps the resolved package names and channel URLs into runtime metadata for status output.

For conda-workspaces projects that keep conda config in pyproject.toml, use [tool.conda.*] table names, such as [tool.conda.workspace] and [tool.conda.feature.ship.dependencies]. For Pixi projects, use Pixi’s [tool.pixi.*] table names, such as [tool.pixi.workspace] and [tool.pixi.feature.ship.dependencies]. [tool.conda-ship] remains a separate tool table because it configures conda-ship, not the workspace solver.

CLI Entry Points#

cs ... is the primary command. When conda-ship is installed in a conda environment, conda ship ... can also be available as a conda-style shortcut for the same builder:

  • cs ... remains the primary CLI.

  • conda ship ... runs the installed cs executable.

  • conda-ship does not require this shortcut to work.

  • the shortcut does not make conda-ship part of conda itself.

The builder identity remains cs, and downstream distributions still own the runtimes they publish.

The Python adapter first looks for the cs executable next to the current Python interpreter, then falls back to PATH. Conda recipes for conda-ship package the Rust-built cs binary and the adapter in the same environment. For adapter tests or custom packaging, CONDA_SHIP_EXECUTABLE points at a specific executable.

Runtime Template Boundary#

The downstream project manifest lives in the downstream repository. The conda-ship builder and generic runtime template come from the conda-ship release or package installation.

cs build copies the selected template, stamps the copy with the runtime name, delegate, install scheme, install name, runtime lock, metadata, and optional embedded bundle. That stamped copy is the runtime. conda-ship then writes the staged artifacts to the downstream project’s output directory. Packaged builds use the runtime template installed next to cs, unless --template points at an explicit template asset. Source checkouts use the same rule and do not compile a runtime template implicitly.