Cache layout#

conda-exec stores cached environments under its base data directory.

Directory structure#

~/.conda/exec/
  run-count                    # automatic cleanup invocation counter
  envs/
    ruff--a3f8b2c1/           # cached env for bare `conda exec ruff`
      conda-meta/
        history               # mtime used for staleness tracking
        *.json                # package records
      bin/                    # (Unix) or Scripts/ (Windows)
        ruff
    samtools--7e2d9f04/       # different tool, different hash
      ...
    ruff--b9e1c3d7/           # same tool, different specs (e.g. --with pytest)
      ...
    script--c5b9979c/         # cached env for a script with inline deps
      conda-meta/
      bin/
        python

Script lockfiles are stored next to scripts, not inside ~/.conda/exec/:

project/
  script.py
  script.py.conda-exec.lock

The exact sidecar name is derived from conda-exec’s selected lockfile format. script.py.conda-exec.lock is the default for the rattler-lock-v6 format. conda-exec also discovers script.conda-exec.lock for that default format.

Embedded lock data lives inside the script in a generated # /// conda-exec-lock block.

Cache key#

Tool cache key#

Each cached tool environment is identified by {tool}--{hash} where:

tool is the package name
hash is the first 16 hex characters of the SHA-256 of the normalized, sorted spec list and channel list

Different version constraints, --with specs, or --channel values produce different cache keys.

Script cache key#

Script environments use the key format script--{hash} where hash is derived from the script’s dependency metadata:

Sorted conda dependencies
Sorted PyPI dependencies
Sorted channels
requires-python value

The hash is computed from the metadata content, not the file path or script code. Changing only the code without changing dependencies reuses the same cached environment. Two different scripts with identical dependency declarations share the same cached environment.

When a script runs from lock data, the cache key is still script--{hash}, but the hash is derived from the lock content. Updating sidecar or embedded lock data creates a distinct cached environment.

Default path#

All platforms use ~/.conda/exec/ (alongside conda’s own data at ~/.conda/).

On Windows, ~ expands to %USERPROFILE% (typically C:\Users\<username>).

Environment variable override#

Set CONDA_EXEC_HOME to override the base directory:

export CONDA_EXEC_HOME=/tmp/conda-exec-test
conda exec ruff check .
# Environment created at /tmp/conda-exec-test/envs/ruff--<hash>/

Staleness tracking#

conda-exec uses conda’s own PrefixData API when it reports cache metadata:

PrefixData.created: creation timestamp when conda can determine one
PrefixData.last_modified: derived from prefix metadata, including conda-meta/history

The conda exec --clean command reads last_modified to determine which environments are stale. conda-exec updates conda-meta/history on cache hits with a one-hour debounce.

Automatic cleanup uses the same staleness data. It stores a best-effort invocation counter in ~/.conda/exec/run-count and checks for stale environments only when the configured interval is reached.