Runtime Data Format

conda-ship stamps runtime data onto a copy of the generic runtime template. This page documents the compatibility surface at a high level. It is not a general-purpose file format for other tools to write.

Important

Treat the stamped runtime data as private executable metadata. Release tooling should read .info.json, .runtime.lock, .packages.txt, and .sha256 instead of parsing or writing bytes inside the runtime binary.

Location

Runtime data is appended to the staged runtime binary.

For embedded builds, the compressed bundle bytes are also appended before the footer. The runtime reads the footer, validates checksums, and then reads the stamped header and optional bundle.

Header Fields

The stamped header records:

schema_version

Runtime data schema version.

runtime_name

Name of the generated runtime executable. Embedded layouts use the z suffix.

runtime_version

Version shown by the generated runtime and written to prefix ownership metadata.

embedded_runtime_name

Conventional embedded runtime name for the same base runtime.

delegate

Executable inside the managed prefix that receives pass-through arguments.

display_name

User-facing runtime name.

install_scheme

Stamped install scheme, such as conda-home or user-data.

install_name

Name used inside the install scheme.

metadata_file

Ownership metadata filename written inside the managed prefix.

bundle_env_var

Runtime-specific environment variable for an external bundle path.

offline_env_var

Runtime-specific environment variable for offline bootstrap mode.

docs_url

Documentation URL shown in runtime help.

install_method

Optional package-manager or installer hint used after uninstall.

runtime_config

Resolved runtime channels and package names used for metadata and status output.

runtime_lock

Runtime lock used for bootstrap.

Footer

The footer contains enough information for the runtime to find and verify the appended data:

• header offset information

• bundle length

• header SHA256

• bundle SHA256

• format version

• conda-ship magic bytes

If the footer or checksums are invalid, the runtime refuses to start.

Compatibility Notes

Generated runtimes are expected to read the format written by the same conda-ship release family. Downstream tools should treat the staged runtime as an opaque executable plus documented artifact metadata files.

Use .info.json, .runtime.lock, .packages.txt, and .sha256 for release automation instead of parsing the appended runtime data directly.