v2026.10.14

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](https://github.com/jdx/mise/pull/14610) (@jdx)

  ```toml
  # ~/.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](https://github.com/jdx/mise/pull/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](https://github.com/jdx/mise/pull/14609) (@jdx, @thernstig)

  ```toml
  [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](https://github.com/jdx/mise/pull/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](https://github.com/jdx/mise/pull/14620), [#14602](https://github.com/jdx/mise/pull/14602) (@jdx)

  ```toml
  [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](https://github.com/jdx/mise/pull/14637) (@jdx)
- **Interactive `mise.toml` reference** in the docs at [configuration/reference](https://mise.jdx.dev/configuration/reference.html). 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](https://github.com/jdx/mise/pull/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](https://github.com/jdx/mise/pull/14629), [#14655](https://github.com/jdx/mise/pull/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](https://github.com/jdx/mise/pull/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](https://github.com/jdx/mise/pull/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](https://github.com/jdx/mise/pull/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](https://github.com/jdx/mise/pull/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](https://github.com/jdx/mise/pull/14616), [#14644](https://github.com/jdx/mise/pull/14644), [#14613](https://github.com/jdx/mise/pull/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](https://github.com/jdx/mise/pull/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](https://github.com/jdx/mise/pull/14597) (@jdx)
- The cargo backend now honors `rename_exe`. Before, it ignored the option and installed the executable under its original name. [#14626](https://github.com/jdx/mise/pull/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](https://github.com/jdx/mise/pull/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](https://github.com/jdx/mise/pull/14595) (@jdx)
- On fish, mise no longer recurses until fish hits its call stack limit after `mise implode`. [#14594](https://github.com/jdx/mise/pull/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](https://github.com/jdx/mise/pull/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](https://github.com/jdx/mise/pull/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](https://github.com/jdx/mise/pull/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**: https://github.com/jdx/mise/compare/v2026.10.13...v2026.10.14

## 💚 Sponsor mise

mise is built and maintained by [@jdx](https://github.com/jdx), an open source developer at [**entire.io**](https://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](https://jdx.dev/sponsors.html). Your support funds ongoing development and helps keep mise fast, free, and independent.