Cache layout#

conda-exec stores cached environments under a platform-specific data directory.

Directory structure#

~/.conda/exec/
  envs/
    ruff--a3f8b2c1/           # cached env for bare `conda exec ruff`
      conda-meta/
        history               # mtime used for staleness tracking
        created_at            # creation timestamp
        *.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

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.

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 for staleness tracking:

conda-meta/created_at: records when the environment was created
conda-meta/history mtime: updated on each conda exec invocation

The conda exec --clean command reads PrefixData.last_modified to determine which environments are stale.