conda-exec 0.4.0

Ephemeral package execution for conda -- run any conda package without installing it

conda-exec

Ephemeral package execution for conda. Run commands from conda packages without installing them permanently.

conda exec ruff check .
ce ruff check .

conda-exec creates a cached, isolated environment for the tool, runs it, and exits. The environment is reused on later runs but is not added to PATH permanently.

conda run, conda exec, or conda global?

Tool	Use it when	Pros	Tradeoffs
conda run	You already have a named or prefix environment and want to run a command inside it.	Built into conda. Works with user-managed project environments. Best fit when an environment is meant to be inspected, activated, exported, or maintained.	You must create and maintain the environment yourself. It does not install the requested command for you. One environment can still become a compatibility bottleneck.
conda exec	You want the command or script invocation to declare the environment it needs.	Keeps base and project environments untouched. Caches isolated environments by spec. Supports extra packages, channels, PEP 723 script metadata, and script locks.	First run solves and installs. Cached environments are an implementation detail, not environments to edit by hand. Commands are not exposed on PATH.
conda global	You want a CLI tool permanently available from your shell.	Installs each tool into an isolated persistent environment. Exposes commands on PATH through trampolines. Records tools in a manifest for update and sync.	It is a tool-install lifecycle, not a per-invocation dependency declaration. Less direct for one-off commands, inline script dependencies, or locked script handoffs.

For Anaconda Project-style command catalogs, use conda exec when each command should carry its own dependency specs, use conda global when a tool should feel installed everywhere, and use conda run when the customer already owns named environments.

Installation

conda install -c conda-forge conda-exec

Install conda-pypi for scripts with PyPI dependencies, and conda-lockfiles for script lock support.

Usage

# Run a tool (creates cached environment on first use)
conda exec ruff check .
ce ruff check .               # standalone alias

# Pin a version
conda exec "ruff>=0.4,<0.5" check .

# Add extra packages
conda exec --with pytest ruff check .
conda exec --with "python=3.12" jupyter lab

# Use a specific channel
conda exec -c bioconda samtools view file.bam

# Run a script with inline dependencies (PEP 723)
conda exec script.py

# Record a repeatable script environment
conda exec --lock script.py

# Force re-creation of cached environment
conda exec --refresh ruff check .

How it works

1. Computes a cache key from the tool name, specs, and channels
2. Checks ~/.conda/exec/envs/ for a cached environment
3. On cache miss: solves and installs via conda's configured solver backend
4. Finds the binary in the environment's bin/ directory
5. Runs it directly via subprocess.run with PATH prepended
6. Forwards the tool's exit code

Documentation

Full documentation at conda-incubator.github.io/conda-exec.

Contributing

pixi install
pixi run check          # lint + format + typecheck
pixi run -e test test   # run tests

License

BSD-3-Clause