mise Updates & Release Notes

bootstrap.user.login_shell now accepts a shell name such as fish instead of a full path. [doctor.checks] can use templates, and vfox backend plugins get their own cache directory. This release also fixes PATH handling in zsh setups that deduplicate PATH, stale task cache hits, a pipx interpreter mix-up on macOS, and removes trust in the compromised eMudhra CA certificates.

It also includes the changes prepared for 2026.10.16, which was tagged but never published: relative and templated write_targets paths, version aliases from vfox backend plugins, keyring passwords for private PyPI indexes, vfox-backend: packslip plugin sources, and a change to where find_up starts (see Changed and Upgrading).

Added

[bootstrap.user].login_shell accepts a shell name. A config shared across machines no longer needs to know where each system installs the shell. mise looks up the name when it checks or applies the setting, which happens after bootstrap.packages has installed the shell. It searches PATH first (never the mise shims directory), then common package-manager locations: /opt/homebrew/bin, /usr/local/bin, /home/linuxbrew/.linuxbrew/bin, ~/.linuxbrew/bin, /usr/bin and /bin. If no executable is found, mise bootstrap user apply fails without changing /etc/shells or the account, and status reports not installed. mise bootstrap user status shows the path it found, and --json output has a new resolved field. Absolute paths work as before. #14770 (@jdx)

[bootstrap.packages]
"brew:fish" = "latest"
[bootstrap.user]
login_shell = "fish"

Doctor checks support templates. run, description and hint in [doctor.checks.*] are rendered with the template context of the config file that declares them, the same way hooks are. A check can now use a value from [vars] instead of hard-coding it. dir is not rendered. If a template fails, only that check reports ERROR and the other checks still run. Text that already contains {{ or {% in these fields is now parsed as a template. #14771 (@jdx)

[doctor.checks."project-a:env"]
description = "project-a has a .env file"
run = 'test -f {{ vars.repos_dir | quote }}/project-a/.env'
hint = "cp {{ vars.repos_dir }}/project-a/.env.example {{ vars.repos_dir }}/project-a/.env"

vfox plugins get RUNTIME.cacheDirPath. This is a cache directory for each plugin at $MISE_CACHE_DIR/plugins/<plugin-name>. mise creates it before running any hook, and every hook of the plugin sees the same path. Unlike pluginDirPath, it is kept when the plugin is reinstalled. mise cache clear deletes it, so plugins must handle it being missing. It is nil when no cache directory is available. #14776 (@jdx)

settings.write_targets accepts relative and templated paths. Before, only absolute or ~/ paths worked, so dotfiles shared between machines with different MISE_CONFIG_DIR or XDG_CONFIG_HOME had to hardcode the config directory. Templates are now rendered, and a relative result is joined to the config_root of the settings file that declares it. For a global file that is $HOME, so the portable spelling uses the file's own directory. The resolved path must still be a global config file that mise loads. If a template fails to render, mise warns, and mise use --global fails with "must resolve to an absolute path" instead of writing to the default file. #14742 (@jdx)

# ~/.config/mise/conf.d/settings.toml
[settings.write_targets]
tools = "{{ config_source | dirname }}/tools.toml"

vfox backend plugins can report version aliases. BackendListVersions can return an aliases table, so a registry's moving names resolve to real versions. Before, "mise-ghcup:ghc" = "recommended" passed the literal string to the plugin, installed into installs/.../recommended, never followed the tag when it moved, and showed recommended in mise ls and the lockfile. Now ghc@recommended resolves to 9.10.3, installs into 9.10.3/, and the lockfile records 9.10.3. Aliases you define in config still win. They are cached like the version list, and an expired cache still answers offline. Older mise versions ignore the aliases field, so plugins can adopt it right away. #14732 (@jdx, @cprecioso)

return {
versions = { "9.8.4", "9.10.3", "9.14.1" },
aliases = { recommended = "9.10.3" },
}

mise lock and version listing work with a PyPI index that uses a keyring. With an index such as Azure Artifacts and artifacts-keyring, mise install worked because uv read the password from its keyring provider, but mise's own requests sent no credentials and failed with 401 Unauthorized. Set the new pypi.keyring_provider (disabled by default, or subprocess; env var MISE_PYPI_KEYRING_PROVIDER) and give the registry URL a username without a password. mise then runs keyring get <url> <username>, as uv does, and sends the result as HTTP Basic credentials when it lists versions and when mise lock reads a release's requires-python. The password is never written to the lockfile or the version cache. The keyring executable must be on PATH. If it is missing or has no entry, mise sends the request without credentials. #14733 (@jdx)

[settings.pypi]
keyring_provider = "subprocess"
registry_url = "https://[email protected]/org/project/_packaging/feed/pypi/simple/{}/"

vfox-backend: works as a prefix for packslip plugin sources. A vfox backend plugin can be installed from a signed packslip archive, both from the CLI and in [plugins]. Before, mise plugins install vfox-backend:foo 'packslip:owner/repo#1.0.0' failed with packslip plugin sources require the vfox plugin type. An explicit asdf: or package: prefix is still rejected, and the error now says "vfox or vfox-backend". The archive still declares extensions.mise.plugin = "vfox". #14727 (@jdx)

mise plugins install vfox-backend:my-backend 'packslip:your-org/my-backend#1.0.0'

mise bootstrap packages list is now an alias for status, alongside ls. #14709 (@himkt)

Changed

find_up in env._.file starts at the config root. Every other relative path in a config resolves against the config root, but find_up started at the current directory. A relative find_up path now starts at the config root and walks up through its parents, which suits a monorepo whose root .env applies to every package. An absolute path starts at its own directory. A global config that wants to search from wherever mise runs can use cwd. The env_file setting still discovers dotenv files up from the current directory and is unchanged. See Upgrading. #14734 (@jdx, @thernstig)

# ~/.config/mise/config.toml
[env]
_.file = { path = "{{cwd}}/.env", find_up = true }

allow_builds approves only the packages it lists. With the embedded aube installer, allow_builds = ["re2"] also ran the install scripts of every package on aube's bundled trusted-dependencies list, such as dtrace-provider. For a package list, mise now turns that default list off, so only the packages you name build. allow_builds = true and the default with no option are unchanged. This updates the embedded aube to 2.8.0. #14731 (@jdx)

Fixed

exec() in [env] values, and other commands mise runs with the pre-activation environment, can now find commands in a _.path directory that was already on PATH before activation, even if the shell deduplicates PATH (for example zsh with typeset -U path PATH). #14772 (@jdx)

With task.source_freshness_hash_contents = true, a task now re-runs when a source file is changed to content of the same size and its old mtime is restored (for example by rsync -a, cp -p or touch -r). On Unix, mise now also compares the file's ctime. Cache entries written by older versions are rehashed once. #14778 (@jdx)

On macOS, pipx: installs no longer fail when aqua:aws/aws-cli is in the toolset. Because macOS filesystems ignore case by default, mise's lookup for python matched aws-cli's executable Python shared library and passed it to uv as the interpreter. This lookup now requires the exact case. #14769 (@jdx)

An aqua registry template with an unterminated string literal now fails with an "unterminated string literal" error instead of hanging. Escaped quotes after backslashes are also detected correctly. #14752 (@Huge, @jdx)

The built-in npm backend no longer trusts the eight eMudhra intermediate CA certificates whose private keys were compromised. The fix comes from updating its bundled root certificates (webpki-root-certs 1.0.10, rustls-webpki 0.103.16). Builds that use the OS trust store are fixed by OS updates instead. #14781 (@jdx)

A [bootstrap.compose] project no longer reports drift on every run when a service uses a service: reference such as network_mode: service:vpn. Compose hashes the reference as written but stamps the container with the hash of the resolved container:<id>, so the two never matched. mise now pins these references (network_mode, ipc, pid, volumes_from) to the running container before it asks compose for the hash. This needs an explicit files list in the project's config. Projects without one hash as before. #14729 (@jdx)

vfox plugins now keep symlinks when they extract .zip archives returned by PreInstall. Before, entries such as bin/npm -> ../lib/node_modules/npm/bin/npm-cli.js became regular files holding the link target, and the tool failed with No such file or directory. Links that resolve outside the install directory are still rejected. The http: backend and tarballs were not affected. #14730 (@jdx)

[daemons.<name>] task = "worker" now finds a file task such as .mise/tasks/worker.sh, as mise run worker does. Before, it failed with daemon srv runs unknown task "worker" unless you wrote worker.sh. #14741 (@jdx)

On Windows, mise self-update no longer replaces the winget mise-shim.exe link with a copy. It updates the real mise-shim.exe next to the real mise.exe. Before, mise reshim kept warning that the shim was older than mise. #14737 (@jdx)

An inherited [dotfiles] entry turned off with only enabled = false no longer prints no recognized operation (block, source, or line), ignoring entry on every command. Other tables with no recognized operation, such as a misspelled line, still warn. #14726 (@jdx, @ponko2)

Upgrading

find_up in a global config: a relative find_up entry in env._.file used to search from the current directory. It now searches from the config root, which is ~ for a global config, so it no longer finds project files. To keep the old behavior, put {{cwd}}/ in front of the path. find_up was added in 2026.10.12.

Documentation

The dotfiles docs now explain that a group entry with only permissions does not inherit the group's mode, so it deploys nothing. Removing mode from an entry that used to deploy a file leaves that file orphaned, and --prune deletes it. To deploy a file and set its permissions, use { mode = "copy", permissions = "0600" }. #14768 (@jdx)

New Contributors

@Huge made their first contribution in #14752

Full Changelog: v2026.10.15...v2026.10.17

💚 Sponsor mise

mise is built and maintained by @jdx, an open source developer at entire.io, the title sponsor of his open source work.

If mise saves you or your team time, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep mise fast, free, and independent.

A global config.override.toml can now take precedence over project config, and mise config explain describes each key in a config file. Paranoid mode can be turned on per category, and in that mode dotenv files need their own content-bound trust. Installs now fail when a tool has an option its backend doesn't read, which affects existing configs (see Changed).

Added

Global override files. ~/.config/mise/config.override.toml, and config.<env>.override.toml for each MISE_ENV, rank above every project file, including mise.local.toml and mise.<env>.toml. This covers [env], [tools], [settings], [tasks], hooks and the other sections. Anything the override file doesn't set still comes from the project. mise never writes to these files by default. To write to one, pass --override to use, unuse, set, unset, settings set|add|unset or config get|set. A tool declared in an override file resolves from the global mise.lock and is exempt from the project's --locked check. If MISE_GLOBAL_CONFIG_FILE is set, override files are not loaded. mise config ls shows a Tier column and mise doctor labels the files. #14610 (@jdx)

# ~/.config/mise/config.override.toml
[env]
AWS_PROFILE = "personal"
[tools]
node = "24"

mise config explain [KEY] lists each key a config file sets, with its line number and its description from the schema. It flags unknown keys with a "did you mean" suggestion and marks deprecated keys. It reads the file as plain TOML, so it also works on a config mise refuses to load. Pass a key such as tasks to show only that section, --json for machine-readable output, and --file, --global, --system or --override to pick a file. #14642 (@jdx)

Paranoid mode can be turned on per category. paranoid now accepts a list of config, env_files, plugins and provenance in addition to true/false. MISE_PARANOID=config,env_files also works. true still turns on all four categories. An unknown category name is an error. #14609 (@jdx, @thernstig)

[settings]
paranoid = ["env_files"]

env_file takes several filenames, for example env_file = [".env", ".env.local"] or MISE_ENV_FILE=.env:.env.local. The file nearest the current directory wins. Within one directory, a name later in the list wins. A single string still works. #14606 (@jdx, @thernstig)

A find_up entry in env._.file can search several names together. Give one entry a path list, and mise searches directory by directory. The closest directory wins, then the later name within a directory. With two separate entries, a .env.local in a parent directory still overrides the project's .env. The docs now explain this difference and how env_file differs from _.file. #14620, #14602 (@jdx)

[env]
_.file = { path = [".env", ".env.local"], find_up = true }

#MISE headers in file tasks accept the same keys as [tasks.<name>], including timeout, vars and the deny_*/allow_* sandbox keys. Before, these keys were ignored with a warning. If one header value is invalid, mise warns and skips that key, and every other task still loads. An invalid confirm or deny_* value is still an error, so a typo can't remove a confirmation prompt or a sandbox restriction. Before, a template named with extends overrode a header's silent. Now the header's value wins. #14637 (@jdx)

Interactive mise.toml reference in the docs at configuration/reference. It lists every key with its type, choices and default, and you can filter keys and link to them directly. Plain Markdown copies are also published for agents. #14641 (@jdx)

Changed

Installs fail on tool options the backend doesn't read. Before, such options were silently ignored. A typo or a key meant for another backend now stops the install, and the error names the option: cargo:eza: option 'asset_pattern' is not used by the cargo backend. Keys under platforms are checked too. So far this applies to the cargo, conda, gem, github, gitlab, forgejo, go, http, npm, packslip, pipx, s3, spinel, spm and ubi backends. aqua, plugin and core-language tools are not checked. The npm backend accepts the checksum option that comes from a packageManager field in package.json. #14629, #14655 (@jdx)

Paranoid mode needs content-bound trust for env files. In paranoid mode, files loaded through _.file, found by the env_file setting, or run by _.source each need their own trust. Editing one of these files revokes its trust. Before, trusting mise.toml also approved these files, and later edits went unchecked. Running mise trust with no path trusts the project's config and every env file it loads. The error names the file but prints none of its values. To exempt a file by path, add it to trusted_config_paths in your global config. With a category list, this check belongs to env_files. #14604 (@jdx, @thernstig)

More specific config error messages.

A warning about an unknown mise.toml key now gives the line and column, and suggests a close match, for example mise.toml:5:1: settings.experimantal (did you mean experimental?). #14639 (@jdx)

A wrong value for a hook, a task run/depends entry or an [env] variable now says which forms are accepted, or names the unknown key. Before, the error was data did not match any variant of untagged enum. An unknown key in a run or depends table now gets a warning. Before, it was silently ignored. #14640 (@jdx)

[bootstrap.linux.firewall] is validated on every OS. macOS and Windows still skip the section at bootstrap time, but an invalid value such as backend = "iptables" is now an error there too. #14615 (@jdx)

Editor schema updates. Editors now flag unknown keys in most [bootstrap] tables and in [dotfiles] entries. The schema now documents launchd keep_alive_on_failure and nice, and dotfile autosave and enabled. It also accepts valid configs it used to reject: templated login_shell, queue_directories and umask, nested macOS defaults values, and tools on [vars] entries. On Windows, [bootstrap.brew].adopt no longer causes an unknown-field warning. #14616, #14644, #14613 (@jdx)

mise dot status and mise dot sync are faster with many tracked files. They start one git process per tracked file instead of three, which took about 10s down to 4s for 860 files. #14607 (@waynehoover)

Fixed

With an external rustup that keeps its proxies in a shared directory, such as pacman's /usr/bin, mise no longer puts that directory ahead of its own tools. Before, mise exec -- node could run the system Node. Only the Rust proxies are now exposed, through a directory that mise owns. #14597 (@jdx)

The cargo backend now honors rename_exe. Before, it ignored the option and installed the executable under its original name. #14626 (@jdx)

Locked pypi: installs through uv now pass the configured mise Python to uv sync. Before, mise passed an empty path, so uv could pick another interpreter and fail on --no-build tools such as yamllint. #14593 (@jdx, @hollow)

When the TLS root store or a CA file can't be loaded, the npm backend now reports an error instead of crashing mise with a core dump. #14595 (@jdx)

On fish, mise no longer recurses until fish hits its call stack limit after mise implode. #14594 (@jdx, @thernstig)

mise bootstrap now finds Nix in /nix/var/nix/profiles/default/bin when a pre-packages hook installed it earlier in the same run, so nix: packages install. #14596 (@jdx)

MISE_WATCH_FILES_GIT_REWRITTEN is no longer set when HEAD stayed on the same commit, for example after git checkout -b, git reset or git branch -m. Before, format-on-edit hooks skipped files you had just edited. #14585 (@JamBalaya56562)

Command wrapper templates can now use config_root and config_source. Relative paths in template functions resolve from the wrapper's config file instead of the current directory. #14628 (@JamBalaya56562)

Upgrading

• Unsupported tool options: if an install now fails with option '...' is not used by the ... backend, remove the option or fix its spelling. mise config explain tools shows which keys mise doesn't recognize.
• Paranoid mode: after upgrading, run mise trust in each project to approve its env files. Run it again after editing them. If you only want the env-file check, set paranoid = ["env_files"].
• Firewall config on macOS and Windows: if a shared config has an invalid [bootstrap.linux.firewall] value, it now fails to load on macOS and Windows too. Correct the value.

Full Changelog: v2026.10.13...v2026.10.14

💚 Sponsor mise

mise is built and maintained by @jdx, an open source developer at entire.io, the title sponsor of his open source work.

If mise saves you or your team time, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep mise fast, free, and independent.

mise now ignores [settings] in a project config until you trust it. This release also adds per-version-range backend options to the registry and template support for command wrappers and [bootstrap.repos]. It fixes several bugs in lockfiles, tasks and multi-version tool options.

Security

[settings] from untrusted project configs is ignored. Before, a cloned repo's mise.toml could change settings as soon as mise found it, with no trust prompt. That included settings that redirect downloads or feed build commands, such as node.mirror_url, python.pyenv_repo and ruby.precompiled_url. These settings now apply only after mise trust, like [env], [hooks] and [tools] options already did. Trusted projects, global and system config, environment variables and CLI flags work as before. Commands that trust the active config implicitly (mise run, mise exec, mise install) reload settings after trusting it, so the project's settings still apply to that same command. Settings files are now parsed once per load. #14538, #14553 (@jdx)

For example, if an untrusted repo sets [settings.python] pyenv_repo to its own URL, mise settings get python.pyenv_repo returns the default pyenv repository until you run mise trust.

mise's own zip dependency moved to 9.x, which fixes GHSA-4684-h2q9-2vcp. Older versions applied Unix permissions through extracted symlinks without checking that the target stayed inside the destination. mise uses this code to extract downloaded .zip tool archives. #14577 (@jdx)

Added

One registry backend can carry different options for each version range. A registry entry can list the same backend more than once, each time with its own min_version/max_version and options. Tools whose release assets changed at some version can then stay on one backend. Two entries can't give the same version different options unless their platforms don't overlap. Table syntax such as tool = { version = "1.4.0" } now takes its registry defaults from the entry that version selects. Older mise releases apply only the first entry's options to every version. #14543 (@jdx)

backends = [
  { full = "github:example/tool", min_version = "2.0.0", options = { asset_pattern = "tool-v2-*" } },
  { full = "github:example/tool", max_version = "2.0.0", options = { asset_pattern = "tool-*" } },
]

mise ls-remote lists every version range of a registry tool. When a tool's backends serve different version ranges, mise now lists each range from the backend that serves it. Before, it listed only the first backend's range. For example, mise ls-remote hk now starts at 0.1.4 instead of 1.58.1. Explicit backends, overrides, --all and --strict-metadata behave as before. #14544 (@jdx)

Command wrapper values render as templates. command, args and env in [wrappers] can use vars, env and the usual template functions. tools and config_root are not available. A command that renders blank is an error. Use {% raw %} to keep literal braces, such as Docker's {{.Names}}. #14565 (@jdx)

[wrappers.foo]
command = "foo-real"
args = ["--mode={{ vars.mode }}"]
env = { FOO_HOME = "{{ [xdg_data_home, 'foo'] | join_path }}" }

[bootstrap.repos] supports templated url/ref and clone options. url and ref render from [vars] or the process environment. Values from a config's [env] table are not available. filter, depth and submodules = true are passed to the first git clone as --filter, --depth and --recurse-submodules. Existing checkouts are left as they are. depth can't be combined with a commit SHA or a refs/… ref. #14548 (@jdx, @ovidiubuligan)

[bootstrap.repos]
"~/src/large" = { url = "[email protected]:example/large.git", ref = "{{ vars.branch }}", filter = "blob:none", depth = 1 }

{{ system_brew_prefix }} template variable. It resolves to the Homebrew prefix that mise bootstrap installs into: /opt/homebrew on macOS and /home/linuxbrew/.linuxbrew on Linux, or the value of MISE_SYSTEM_BREW_PREFIX. It does not detect a Homebrew install somewhere else. [bootstrap.user].login_shell now renders templates too, so login_shell = "{{ system_brew_prefix }}/bin/zsh" works. #14572, #14570 (@jdx)

vfox PreInstall hooks can return a headers table next to url and sha256. Plugins can now download private or token-gated artifacts through the normal install path, which handles checksums, retries and lockfile URLs. Headers are sent only to the origin of url, are dropped on cross-origin redirects, are redacted in debug output and are never written to mise.lock. An explicit Authorization header overrides netrc and the automatic GitHub token. #14531 (@jdx)

mise doctor reports a stale mise-shim.exe on Windows. In windows_shim_mode = "exe", shims are copies of the mise-shim.exe that sits beside mise.exe. If that template is older than mise, or has no version tag (every template built before this release), mise doctor reports it and mise reshim warns. To fix it, update mise with the package manager that installed it, or run mise self-update, and then run mise reshim --force. #14586 (@jdx)

Fixed

Lockfiles

Running mise lock on Windows now records ruby entries for Windows, Linux and macOS platforms. Before, it skipped them, and mise install --locked then failed. #14520, #14529 (@jdx)

Commands that rewrite mise.lock without locking again, such as mise link, no longer delete other platforms' option variants (for example, per-platform asset_pattern entries). #14519 (@jdx)

A mise link for one version of a tool no longer makes mise install --locked fail for that tool's other versions. A link now bypasses the lockfile only when the requested version could select it. #14539 (@jdx)

mise install --locked for Java no longer fetches the mise-java catalog when mise.lock already has the download URL, so locked installs work in air-gapped or proxied environments. #14534 (@jdx)

Tasks and shims

mise run no longer hangs when parallel tasks need to install the same tool. #14536 (@jdx)

Running mise install inside a task no longer removes the shims for that task's lazy tools. #14533 (@jdx)

Task hooks (such as postinstall = { task = "setup" }) and watch_files task hooks now run with mise even when a tool shim triggered them. Before, they could fail with errors like jq: Unknown option --cd. #14550 (@jdx, @alitas)

mise watch exits quietly with status 130 when you interrupt watchexec with Ctrl+C, instead of printing an error. #14541 (@jdx)

Per-version tool options

When a github:, gitlab: or forgejo: tool lists several versions in config, each version now installs with its own options. Before, an option such as rename_exe set only on the first entry applied to every version. #14537 (@JamBalaya56562)

vfox: plugin hooks now receive only the options configured for the version they handle. #14562 (@JamBalaya56562)

mise install now restores cargo, rustc and the host's rust-std when they are missing from a Rust toolchain with the minimal or default profile. Before, mise reported such a toolchain as installed. #14525 (@JamBalaya56562, @risu729)

The uv, pip and poetry deps providers now run again after mise recreates a deleted venv in a later process. Before, the new venv stayed empty. #14532 (@halms)

vfox plugins now report an error, instead of crashing mise, when the HTTP client can't be built (for example, when no CA certificates are installed). #14576 (@JamBalaya56562)

MCP resource read errors now include the underlying cause, such as the untrusted-config message and its mise trust hint. #14566 (@diogochaves)

Registry

xcsift 1.7.0 and later installs from signed Packslip releases and now supports Linux x64 as well as macOS ARM64. #14540 (@jdx)

protoc-gen-connect-go 2.x now installs from the /v2 Go module path, and 1.x versions keep working. #14545 (@jdx)

Added rea (npm:rea-agents). #14421 (@phucisstupid)

Documentation

The docs now state that OpenTelemetry export and spinel installs require experimental = true. #14552 (@ZainnQureshii)

New Contributors

• @phucisstupid made their first contribution in #14421
• @diogochaves made their first contribution in #14566
• @ZainnQureshii made their first contribution in #14552
• @fang2hou made their first contribution in #14551

Full Changelog: v2026.10.12...v2026.10.13

💚 Sponsor mise

mise is built and maintained by @jdx, an open source developer at entire.io, the title sponsor of his open source work.

If mise saves you or your team time, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep mise fast, free, and independent.