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.

用于报告最新版本的命令（mise outdated、mise upgrade、mise ls-remote、mise lock 和 mise latest）会在版本列表超过 fetch_remote_versions_cache 指定的时长后重新获取；该时长默认为 1 小时。

只需要查找符合请求的版本的命令（例如 mise install、mise use 和 mise run）会缓存列表，时长为工具的 minimum_release_age 减去 1 小时（版本主机快照最多会延迟 1 小时），范围为 1 到 24 小时：默认截止时间下为 23 小时；工具设置 minimum_release_age = "6h" 时为 5 小时；关闭截止时间时为 1 小时。无论如何，列表中尚未达到该等待时长的发行版本都不能安装。若列表没有为每个版本记录日期，或你自行设置了 fetch_remote_versions_cache，则列表会改为在 fetch_remote_versions_cache 指定的时长后重新获取。

同一缓存时长也适用于一次代表多个工具版本列表的 mise-versions 索引，以及 pipx: 工具注册表报告的最新发行版（即同一列表中日期最新的发行版）。维护者可以将 latest 指针移至任意版本，例如 npm 的 latest dist-tag 或 asdf 插件的 latest-stable 脚本；这类指针仍会在 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.