Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Overview

conda-dist is a command-line tool that converts a Conda environment manifest into deliverables. It reads a single conda-dist.toml file, resolves the requested packages, and prepares the build artifacts.

Available output families include:

  • Native installers that unpack the environment into a user-specified prefix.
  • OCI container images that embed the environment on top of a minimal base.
  • Native packages (RPM/DEB) built for Linux targets.

The remaining chapters document the manifest format and describe how each backend consumes it.

Configuration Reference

conda-dist reads a single TOML manifest. Every command consumes the same configuration, so you describe the environment once and reuse it for installers, containers, or other outputs. A minimal manifest looks like:

name = "myapp"
version = "1.2.0"
author = "John Doe"
channels = ["conda-forge"]
platforms = ["linux-64", "osx-arm64"]

[dependencies]
python = "3.11.*"
pandas = "^2.2"

The remaining sections document each supported key, including optional tables for format-specific settings.

Common Settings

These keys apply to every build target and appear at the top level of the manifest.

Required fields

  • name — ASCII string composed of letters, digits, -, _, or .. Used when naming installers, archives, and tags.
  • version — ASCII string without whitespace. Appended to artifact names and container tags.
  • author — Free-form maintainer identifier bundled into metadata.
  • channels — Non-empty array of Conda channels evaluated in order of precedence.
  • platforms — Non-empty array of Conda platforms (for example linux-64, osx-arm64). Each platform yields a distinct installer executable.

Dependencies

Declare package requirements with a table of Conda match specs:

[dependencies]
python = "3.11.*"
pandas = "^2.2"

Metadata

Populate optional descriptive fields for installers and summary output:

[metadata]
summary = "MyApp command suite"
description = "Command-line utilities for data preparation."
release_notes = "- Initial publication."
featured_packages = ["python", "pandas"]

Virtual packages

conda-dist seeds each platform with sensible defaults for synthetic virtual packages instead of probing the build host. Override values only when you need to pin a specific runtime characteristic.

[virtual_packages.default]
linux = "5.15"
libc = { family = "glibc", version = "2.31" }

[virtual_packages.linux-64]
cuda = "12.2"

Use the default table for cross-platform values and add per-platform tables to override individual targets. Supported keys are linux, osx, win, libc, and cuda.

Container Settings

[container] configures OCI image output.

[container]
base_image = "gcr.io/distroless/base-debian12"
prefix = "/opt/env"
tag_template = "registry.internal.example.com/analytics/{name}:{version}-py311"
  • base_image (optional) defaults to gcr.io/distroless/base-debian12.
  • prefix (optional) relocates the Conda environment inside the image. Supply an absolute path; the default is /opt/conda.
  • tag_template (optional) renders the final tag. Only {name} and {version} are recognised placeholders. The default template is {name}:{version}.

Container builds emit <name>-container.oci.tar alongside the manifest unless you override the output location on the command line.

Output Formats

Output formats consume the manifest and emit distributable artifacts. Each one reuses the same dependency resolution step, then applies backend-specific packaging.

  • Installers — produce native self-extracting executables per target platform.
  • Container images — stage the environment into a minimal base and output an OCI archive.
  • Native packages — produce RPM and DEB artifacts for Linux distributions.

Subsequent sections describe the behaviour and outputs of each format.

Installers

conda-dist installer <manifest> produces a native self-extracting installer for each target platform.

Usage Example

conda-dist installer app.toml
./app-linux-64 /opt/app
/opt/app/bin/python --version

The command caches downloads and writes one native installer executable per platform (defaulting to <name>-<platform> in the manifest directory). Each installer unpacks the bundled environment into the installation path you provide, with no external runtime requirements.

Characteristics

  • Output: Native executable archive, one per target platform.
  • Installation prefix: User-supplied path, installable anywhere.
  • Runtime dependencies: None required on the target host.
  • Reproducibility: Bundles the locked package set used at build time.
  • Transport: Compressed payload suitable for artifact stores or offline delivery.

Container Images

conda-dist container <manifest> builds an OCI image from the manifest.

Usage Example

conda-dist container app.toml
skopeo copy oci-archive:app-container.oci.tar docker-daemon://app:1.0.0
docker run app:1.0.0 env/bin/python --version

conda-dist container stages the resolved environment on the configured base image and writes an OCI archive (default <name>-container.oci.tar alongside the manifest). The example uses skopeo to load the archive into a Docker daemon; any OCI-aware transport can be substituted.

Characteristics

  • Output: OCI archive suitable for use with Docker, Kubernetes, etc.
  • Base image: Configurable (defaults to gcr.io/distroless/base-debian12).
  • Footprint: Distroless base plus the packaged environment keeps layers minimal.
  • Multi-architecture: Multiple platforms yield a single tag backed by per-platform images.

Native Packages

conda-dist package <manifest> builds RPM and DEB archives for Linux targets.

Usage Example

conda-dist package app.toml \
  --rpm-image rockylinux:9 \
  --deb-image ubuntu:24.04

Packages are written beneath <output-dir>/<image>/, grouped by the container image used. The output directory defaults to the manifest directory, and each image directory contains the generated RPM/DEB artifacts.

Characteristics

  • Output: RPM/DEB archives organized per container image.
  • Platforms: Supports all Linux targets listed in the manifest.
  • Images: Works with docker/podman-compatible distribution images.
  • Runtime dependencies: None required on the target host.

CLI Reference

conda-dist

NAME

conda-dist - Build distributable artifacts from Conda environments

SYNOPSIS

conda-dist [--work-dir] [--locked] [--unlock] [-h|--help] [-V|--version] <subcommands>

DESCRIPTION

Build distributable artifacts from Conda environments

OPTIONS

--work-dir <PATH>
Workspace directory used for cached artifacts (defaults to <manifest>/.conda-dist)

--locked
Require the existing lockfile and skip solving; fails if the lockfile is stale or missing

--unlock
Regenerate the lockfile even if one already exists

-h, --help
Print help

-V, --version
Print version

SUBCOMMANDS

conda-dist-lock(1)
Update or validate the lockfile without producing artifacts

conda-dist-installer(1)
Build self-extracting installers

conda-dist-container(1)
Build container images embedding the environment

conda-dist-package(1)
Build native system packages (rpm/deb) using containerized installers

conda-dist-help(1)
Print this message or the help of the given subcommand(s)

VERSION

v0.1.0

conda-dist container

NAME

container - Build container images embedding the environment

SYNOPSIS

conda-dist container [--platform] [--engine] [--oci-output] [-h|--help] [MANIFEST]

DESCRIPTION

Build container images embedding the environment

OPTIONS

--platform <PLATFORM>
Restrict the build to a single target platform

--engine <PATH>
Path to the container engine binary (defaults to docker, then podman)

--oci-output <PATH>
Path to write the resulting OCI archive (defaults to <manifest-dir>/<name>-container.oci.tar)

-h, --help
Print help

[MANIFEST] [default: conda-dist.toml]
Path to the conda-dist manifest (conda-dist.toml)

conda-dist installer

NAME

installer - Build self-extracting installers

SYNOPSIS

conda-dist installer [--output-dir] [--installer-platform] [-h|--help] [MANIFEST]

DESCRIPTION

Build self-extracting installers

OPTIONS

--output-dir <PATH>
Optional directory to write the installer binary

--installer-platform <PLATFORM> [default: all]
Select which installer platform(s) to build

-h, --help
Print help

[MANIFEST] [default: conda-dist.toml]
Path to the conda-dist manifest (conda-dist.toml)

conda-dist lock

NAME

lock - Update or validate the lockfile without producing artifacts

SYNOPSIS

conda-dist lock [-h|--help] [MANIFEST]

DESCRIPTION

Update or validate the lockfile without producing artifacts

OPTIONS

-h, --help
Print help

[MANIFEST] [default: conda-dist.toml]
Path to the conda-dist manifest (conda-dist.toml)

conda-dist package

NAME

package - Build native system packages (rpm/deb) using containerized installers

SYNOPSIS

conda-dist package [--engine] [--rpm-image] [--deb-image] [--platform] [--output-dir] [-h|--help] [MANIFEST]

DESCRIPTION

Build native system packages (rpm/deb) using containerized installers

OPTIONS

--engine <PATH>
Path to the container engine binary (defaults to docker, then podman)

--rpm-image <IMAGE>
Build RPM packages using the specified container image (repeatable)

--deb-image <IMAGE>
Build DEB packages using the specified container image (repeatable)

--platform <PLATFORM>
Restrict native packaging to specific target platform(s) (defaults to host platform)

--output-dir <PATH>
Output directory for generated packages (defaults to <manifest-dir>)

-h, --help
Print help

[MANIFEST] [default: conda-dist.toml]
Path to the conda-dist manifest (conda-dist.toml)