Configuration#

Build-Time Configuration#

conda-express is a downstream distribution built by conda-ship. The package set is maintained in the runtime source environment in pyproject.toml, and [tool.conda-ship] tells conda-ship which solved environment becomes the runtime:

[tool.conda-ship]
runtime-name = "cx"
runtime-version = { from = "project-metadata" }
delegate-executable = "conda"
artifact-layout = "online"
source-environment = "runtime"
exclude-packages = ["conda-libmamba-solver"]
docs-url = "https://jezdez.github.io/conda-express/"
install-scheme = "conda-home"
install-name = "express"

The release workflows override artifact-layout and artifact-name:

artifact-layout = "online" with artifact-name = "cx" builds cx
artifact-layout = "embedded" with artifact-name = "cxz" builds cxz

The source environment is solved and locked by Pixi. conda-ship derives the runtime lock from that committed source lock rather than accepting ad hoc package and channel lists in the workflow. See source locks and runtime locks for the generic distinction between project input and runtime output.

Note

This page documents conda-express’s distribution configuration. To build a different runtime, use conda-ship’s configuration reference instead of copying conda-express’s defaults.

Runtime Package Set#

The runtime source environment installs:

Package	Role
`python >=3.12`	Python runtime for conda
`conda ==26.5.2`	Package manager
`conda-rattler-solver`	Default solver
`conda-spawn >=0.1.0`	Subshell activation
`conda-completion >=0.3.0`	Shell completion for `cx` and conda plugin commands
`conda-exec >=0.3.0`	Ephemeral package execution and PEP 723 script workflows
`conda-pypi`	PyPI interoperability
`conda-self`	Base environment self-management and reset
`conda-global`	Global tool environments
`conda-workspaces >=0.7.0`	Workspace manifests and tasks

conda-libmamba-solver is excluded from the derived runtime lock because conda-express uses conda-rattler-solver.

Versioning Policy#

conda-express release versions follow the exact conda package version in the runtime lock. A 26.5.2.post4 conda-express release bootstraps conda 26.5.2 on every supported platform.

Use .postN releases for conda-express-only rebuilds that keep the same conda runtime package, for example 26.5.2.post1.

See Features for why the distribution version follows the conda runtime version.

Install Location#

The stamped install scheme is conda-home and the install name is express. That makes the default install path:

~/.conda/express

Users can override the install path for a command with the runtime-level --path option:

cx --path /opt/cx bootstrap
cx --path /opt/cx status

--path is intentionally a runtime option, not build configuration. The published cx binary stays cross-platform while advanced users, CI jobs, and installer smoke tests can choose a local path at runtime.

conda-ship owns the generic install scheme behavior and runtime ownership metadata. See install locations and ownership for the builder-level rules behind conda-home, user-data, install names, and prefix ownership checks.

Runtime Metadata#

Generated conda-ship runtimes write ownership metadata into each managed install path. cx status, cx bootstrap --force, and cx uninstall use that metadata to avoid taking over or deleting unrelated conda installations.

Bootstrap also writes standard conda prefix metadata:

conda-meta/history
conda-meta/initial-state.explicit.txt

history lets conda recognize ~/.conda/express as an environment. The initial-state file records the exact packages installed from the stamped runtime lock, including package URLs and checksums. The included conda-self plugin can use that snapshot to reset the managed base prefix to the shipped package set:

cx self reset --snapshot installer-exact

The managed base environment is also protected with a CEP 22 frozen marker after bootstrap. Day-to-day work should happen in named environments:

cx create -n analysis python=3.12 numpy pandas
cx shell analysis

Runtime Environment Variables#

These environment variables control bootstrap behavior at runtime. They are useful in native installer post-install scripts, container builds, and CI pipelines.

Variable	Effect
`CX_BUNDLE`	Bundle directory containing `.conda` / `.tar.bz2` archives to pre-populate the package cache from, equivalent to `--bundle`
`CX_OFFLINE`	Disable network access during bootstrap when set to any truthy value, equivalent to `--offline`. Values `0` and `false` are treated as unset

CX_BUNDLE=/Library/Application\ Support/cx/packages CX_OFFLINE=1 cx bootstrap

For custom package sets or new binary distributions, use conda-ship directly instead of treating this repository as a generic builder.