Caches

mise caches tool metadata, computed environments, and task results separately. Start with the cache that matches the symptom: clearing a version list does not reinstall a tool, and clearing the environment cache does not change your config.

mise cache path              # print the cache directory
mise cache clear node        # clear Node.js metadata
mise cache prune --dry-run   # list stale cache files

Tool metadata cache

Backends store metadata under the cache directory, including remote version lists and, depending on the backend, aliases, executable directories, and plugin exec-env output. Read these values through commands such as mise ls-remote node rather than the cache files, whose format can change.

When mise refreshes version lists

Commands that run constantly use cached version lists however old they are, so they never wait on the network: shell activation, mise exec, mise env, mise ls, mise current, mise which, mise where, and shims. They fetch a list only when none is cached.

Commands that report what is newest, mise outdated, mise upgrade, mise ls-remote, mise lock, and mise latest, refetch a list once it is older than fetch_remote_versions_cache, 1 hour by default.

Commands that only need a version matching a request, such as mise install, mise use, and mise run, keep a list for the tool's minimum_release_age less an hour (the most a versions-host snapshot lags), between 1 and 24 hours: 23 hours under the default cutoff, 5 hours for a tool with minimum_release_age = "6h", and 1 hour when the cutoff is off. A release newer than the list could not be installed before it reached that age anyway. Lists that do not date every version, and every list once you set fetch_remote_versions_cache yourself, are refetched after fetch_remote_versions_cache instead.

The same window applies to the mise-versions index that stands in for many tools' lists at once, and to the latest release a pipx: tool's registry reports, which is the newest dated release in that same list. A latest pointer that a maintainer can move to any version, such as npm's latest dist-tag or an asdf plugin's latest-stable script, is still refetched after fetch_remote_versions_cache.

Set prefer_offline to make every command use cached lists the same way, or offline to block network requests entirely.

To see a new release before the cached list expires:

mise cache clear node
mise ls-remote node

Some metadata comes from the versions host, which clearing the local cache does not refresh. A lockfile or a pinned version can also keep a tool on an older version after the list is refreshed.

asdf plugins' exec-env output is cached; run mise cache clear <tool> after you change a plugin.

Environment cache experimental

The experimental env_cache setting caches computed environments on disk. It helps when environment providers are slow or when mise runs nested inside itself:

~/.config/mise/config.toml

[settings]
env_cache = true
env_cache_ttl = "4h"

The cache lives in env-cache/ in the state directory, not in the cache directory. mise activate and mise exec create a session key that nested commands inherit, and a cached environment is reused only with the same key, so an unrelated session computes its own. The cache is encrypted on disk, but any process that inherits the session key can read it.

The cache key covers config paths and modification times, resolved tool versions, relevant settings, the base PATH, and the mise version. Entries expire after env_cache_ttl, and files that env plugins declare as watched invalidate them. Edits to dotenv files or _.source scripts can still leave a nested command with a cached environment; clear or disable the cache when such an edit does not show up. Changes in an external service, such as a rotated secret, are not file changes, so choose a suitable TTL.

mise does not cache secrets. A config with an age-encrypted value, a sops-encrypted _.file, a directive with redact = true, or an env plugin that returns redact = true is never written to the environment cache; mise recomputes that environment every time.

Environment directives cannot opt out of caching one at a time, so a value such as a timestamp template stays the same until the cache expires. Set MISE_ENV_CACHE=0 for a command that needs fresh values:

MISE_ENV_CACHE=0 mise exec -- npm test

Set env_cache = false to turn the cache off for every command. Env plugins declare cacheability and watched files in their MiseEnv return value; see Environment plugins.

mise cache clear also clears cached environments. You do not need to remove installed tools or trust records to refresh an environment.

Task cache

Tasks can skip work when their sources have not changed, or restore cached outputs. This is separate from the metadata and environment caches. For a task named build:

mise cache task build
mise cache clear --task build

--task clears only the entries mise can tie to that task in this project. mise cache clear with no arguments clears everything, including other projects' task caches and the environment cache. See Task caching for configuration and cache keys.

Pruning

mise occasionally deletes cache files that have not been read within cache_prune_age. This is separate from freshness: a version list can be refetched long before its file is old enough to prune.

mise cache prune --dry-run
mise cache prune

Cached environments expire by their own TTL whatever the prune age is. Set cache_prune_age = "0s" to turn off age-based pruning; both the occasional sweep and mise cache prune then stop.

For cache keys in CI, see Continuous integration.