v2026.3.0: : Smarter prepare, task-backed hooks, and per-task vars

Compare Source

This release brings a major upgrade to mise prepare with content-hash freshness, dependency ordering, and better diagnostics. Hooks and watch files can now delegate to full mise tasks, and task vars gain monorepo inheritance and per-task overrides. Several lockfile and idiomatic version file parsing bugs are also fixed.

Highlights

• mise prepare overhaul -- Freshness detection switches from mtime to blake3 content hashing (reliable across CI and clock skew), providers can declare dependencies on each other, a new --explain flag shows detailed diagnostics, and per-provider timeouts are now supported.
• Task-backed hooks -- Hooks and watch_files can now reference mise tasks instead of inline scripts, gaining access to the full task system (deps, env, templating).
• Per-task vars and monorepo vars inheritance -- Tasks can define their own vars that override config-level vars, and monorepo subdirectory vars are now properly inherited when running tasks from the root.

Added

• Task references in hooks and watch_files -- Hooks can now use { task = "name" } syntax to run a mise task instead of an inline script. Mixed arrays of scripts and task references are supported. Task refs respect MISE_NO_HOOKS=1 and the full task system (deps, env, etc.). #​8400 by @​jdx

  [hooks]
  enter = { task = "setup" }
  
  [[watch_files]]
  patterns = ["uv.lock"]
  task = "uv-deps"

• Per-task vars and monorepo vars inheritance -- Tasks can now define task-local vars that override config-level vars for that task. Monorepo subdirectory vars are also properly inherited when running tasks from the project root, matching how env already works. #​8248 by @​halms

  [vars]
  greeting = "hello"
  
  [tasks.test]
  run = 'echo {{vars.greeting}}'
  vars = { greeting = "hi" }   # overrides config-level var

• Built-in git-submodule prepare provider -- A new built-in provider detects .gitmodules and runs git submodule update --init --recursive when submodule directories are stale. No configuration needed -- it activates automatically when .gitmodules exists. #​8407 by @​jdx

• Blake3 content-hash freshness for prepare -- mise prepare now uses blake3 content hashing instead of mtime comparison to determine whether providers need to run. Hashes are persisted to .mise/prepare-state.toml. This is more reliable across CI, VCS operations, and clock skew scenarios. #​8404 by @​jdx

• Human-readable stale reasons in prepare output -- Dry-run and status bar messages now explain why a provider would run, e.g. [dry-run] Would prepare: npm (node_modules does not exist) or prepare: codegen (schema.graphql changed) -- run 'mise prep'. #​8408 by @​jdx

• mise prepare --explain <provider> diagnostics -- A new --explain flag shows detailed information about a specific provider: sources, outputs, auto status, command, and a fresh/stale verdict with reasons. Exits 0 if fresh, 1 if stale, useful for scripting. #​8409 by @​jdx

• Per-provider timeout support for prepare -- Providers can now set a timeout in seconds. If the command exceeds the timeout it is killed. #​8405 by @​jdx

  [prepare.npm]
  timeout = 120  # kill after 2 minutes

• Dependency ordering for prepare providers -- Providers can declare depends = ["other-provider"] to enforce execution ordering. Independent providers still run in parallel. Cycle detection, failure propagation, and unknown-dep warnings are all handled. #​8401 by @​jdx

  [prepare.ansible-galaxy]
  depends = ["uv"]
  run = "ansible-galaxy install -f requirements.yml"
  sources = ["requirements.yml"]
  outputs = [".galaxy-installed"]

Fixed

• Idiomatic version files now ignore comments -- Files like .python-version, .node-version, .ruby-version, and .java-version now correctly strip # comments (both full-line and inline) and blank lines, preventing mise from treating comment text as version specifiers. #​7682 by @​iloveitaly

• Generic parser used for idiomatic files -- Built-in idiomatic file parsers (e.g. for package.json and raw text files) are now used consistently, preventing unexpected behavior when plugins like vfox don't support certain file formats. #​8171 by @​risu729

• Aqua bin_paths disk cache restored with proper invalidation -- The aqua bin_paths.msgpack.z cache removed in v2026.2.24 has been restored with fresh_file invalidation keyed on the install directory. This recovers the 7-11% performance regression on mise env and mise hook-env while keeping cache correctness. #​8398 by @​jdx

• Lockfile no longer splits entries for precompiled settings -- mise lock with precompiled_flavor or similar settings configured no longer produces duplicate tool entries by splitting the host platform into a separate entry. #​8396 by @​jdx

• Python lockfile respects precompiled settings -- mise lock now correctly uses precompiled_arch, precompiled_os, and precompiled_flavor settings when generating Python lock file entries, and precompiled_flavor is properly honored during installs. #​8399 by @​jdx

• "v" prefix normalized in lockfile version matching -- --locked mode no longer fails when mise.toml specifies v1.2.3 but the lockfile stores 1.2.3 (or vice versa). #​8413 by @​jdx

• Vfox no longer eagerly loads metadata -- Removed vfox's idiomatic_filenames() override that triggered plugin metadata loading for every config file check, and reordered detection logic so known patterns are checked first. Eliminates spurious [vfox] Getting metadata for yarn debug messages. #​8397 by @​jdx

• Fixed infinite recursion with uv_venv_auto and uv shims -- When uv_venv_auto = "create|source" is set and a mise shim for uv exists on PATH, venv creation no longer enters infinite subprocess recursion. The fix excludes the mise shims directory from the uv binary search. #​8402 by @​halms

• Improved git submodule parser for prepare -- The .gitmodules parser is now INI-section aware, only extracting path values from [submodule "..."] sections and ignoring comments. Freshness check errors now default to fresh rather than stale, preventing spurious warnings. #​8412 by @​jdx

Breaking Changes

• The deprecated # mise ... file task header syntax has been removed as scheduled. Only #MISE / # [MISE] / //MISE / ::MISE headers are now recognized. If you have task files still using the old # mise headers, update them to use the new syntax. #​8403 by @​jdx

New Contributors

• @​iloveitaly made their first contribution in #​7682

Full Changelog: jdx/mise@v2026.2.24...v2026.3.0

v2026.2.24: : Hooks get Tera templates, aqua cache cleanup, and better error messages

Compare Source

A bug-fix release that enables Tera template rendering in hooks, eliminates a class of stale PATH bugs with aqua tools, improves error messages for unsupported registry tools, and removes the long-deprecated python.venv_auto_create setting.

Fixed

• Hooks now support Tera template rendering -- Hook scripts can now use Tera template variables like {{tools.ripgrep.path}}, just like tasks. Additionally, the install progress bar is now cleared before postinstall hooks run, so hook output is no longer masked by the progress UI. Preinstall hooks correctly skip tools=true env directives since referenced tools may not yet be installed. #​8385 by @​jdx

• Aqua tool PATH entries no longer go stale -- The aqua backend's bin_paths disk cache (bin_paths.msgpack.z) has been removed entirely. This cache provided negligible performance benefit -- reading and decompressing a msgpack file is comparable to parsing the small YAML registry entry -- but was the root cause of stale PATH entries after tool installs (e.g. upgrading uv causing its PATH entry to vanish). The previous fix in v2026.2.23 was raceable by concurrent mise hook-env calls; removing the cache eliminates this class of bugs completely. #​8383 by @​jdx

• Better error when a registry tool has no supported backends -- When a tool exists in the registry but all its backends are filtered out for the current platform or configuration (e.g. imagemagick on a platform where only conda and asdf backends are registered but disabled), the error now clearly explains the situation and lists the registered backends instead of suggesting the user meant the exact tool name they already typed. #​8388 by @​jdx

Removed

• Deprecated python.venv_auto_create setting removed -- The python.venv_auto_create and python_venv_auto_create settings have been fully removed. These were deprecated in favor of the _.python.venv configuration. If you were relying on the legacy virtualenv tool option to auto-create venvs, mise will now warn and print manual creation instructions instead. Migrate to the newer venv configuration: #​8384 by @​jdx

  [tools]
  python = { version = "3.12", _.python.venv = { path = ".venv", create = true } }

Breaking Changes

• The python.venv_auto_create and python_venv_auto_create settings no longer exist. If you still have these in your configuration, they will be silently ignored. Use _.python.venv = { path = ".venv", create = true } in your tool configuration instead. #​8384

Full Changelog: jdx/mise@v2026.2.23...v2026.2.24

v2026.2.23: : Stricter lockfile enforcement and vfox backend options

Compare Source

This release tightens lockfile behavior in --locked mode, fixes a stale PATH cache issue with aqua-based tools, resolves intermittent panics with remote git tasks, and adds the ability to pass custom options to vfox backend plugins.

Added

• Custom options for vfox backend plugins -- Options defined in mise.toml tool entries are now passed through to vfox backend plugins in both BackendInstall and BackendExecEnv contexts, accessible in Lua via ctx.options. This enables custom plugin use cases like controlling build parameters. #​8369 by @​Attempt3035

  [tools]
  "llvm:clang" = { version = "latest", build_cores = "22" }

  function PLUGIN:BackendInstall(ctx)
      local cores = ctx.options.build_cores
      -- use cores in your build logic
  end

• Registry: porter -- Added Porter, a CNAB bundle authoring and management tool (github:getporter/porter). #​8380 by @​lbergnehr

• Registry: entire -- Added entire CLI (aqua:entireio/cli). #​8378 by @​TyceHerrman

• Registry: topgrade -- Added topgrade (aqua:topgrade-rs/topgrade), an all-in-one system upgrade tool. #​8377 by @​TyceHerrman

Fixed

• --locked mode now strictly enforces the lockfile -- Previously, mise lock could still run while --locked was active, mise use tool@latest could bypass the lockfile, and tools missing from the lockfile would silently fall through to remote resolution. Now mise lock refuses to run in locked mode with a clear error and hint, mise use tool@latest respects the lockfile when locked, and missing tools fail fast with an actionable message instead of resolving remotely. #​8362 by @​jdx

• Aqua tool PATH entries no longer go missing after install -- The list_bin_paths() cache could be populated with stale (empty) data before extraction finished, or by a concurrent mise hook-env call during installation. The in-memory and on-disk bin_paths caches are now cleared after an aqua tool install completes so paths are recomputed from the freshly installed files. Fixes an issue where upgrading tools like uv caused their PATH entry to vanish. #​8374 by @​jdx

• Remote git task cache no longer panics or corrupts on concurrent access -- Replaced println!/eprintln! with non-panicking writeln! to handle EPIPE gracefully, and added file locking with clone-to-temp-then-rename to prevent concurrent cache corruption when multiple mise processes fetch the same remote git task simultaneously. #​8375 by @​vmaleze

New Contributors

• @​Attempt3035 made their first contribution in #​8369
• @​lbergnehr made their first contribution in #​8380

Full Changelog: jdx/mise@v2026.2.22...v2026.2.23

v2026.2.22: : Outdated plugins, rename_exe fixes, and smoother installs

Compare Source

A small release adding a new way to check for outdated plugins, along with three bug fixes for archive installs, tool environment resolution, and cross-platform Ruby lockfiles.

Added

• mise plugins ls --outdated flag -- A new -o/--outdated flag checks remote git refs in parallel and displays only plugins where the local SHA differs from the remote. Shows a table with plugin name, URL, ref, local SHA, and remote SHA. Prints "All plugins are up to date" when everything is current. #​8360 by @​jdx

  $ mise plugins ls --outdated
  Plugin  Url                                             Ref   Local    Remote
  tiny    https://github.com/mise-plugins/rtx-tiny.git    main  abc1234  def5678

Fixed

• rename_exe works with archives containing a bin/ subdirectory -- When an archive extracts to a layout like prefix/bin/binary, the rename_exe option was silently skipped because it searched the extraction root non-recursively instead of the bin/ subdirectory where the binary actually lives. Both the GitHub-style backend and the HTTP backend now auto-detect the bin/ subdirectory as the search directory, matching the same logic used by discover_bin_paths() for PATH construction. #​8358 by @​jdx

• Installing cargo/npm/pipx tools no longer crashes with tools = true env directives -- When [env] contained entries like NODE_VERSION = { value = "{{ tools.node.version }}", tools = true }, installing npm/cargo/pipx tools would fail with "Variable not found in context" because the referenced tools might not be installed yet. The cargo, npm, and pipx backends now skip tools = true env directive resolution during installation while still including tool paths in PATH. #​8356 by @​jdx

• Ruby lockfile resolves correct Windows checksums -- Running mise lock on macOS/Linux now correctly resolves RubyInstaller2 binary URLs and checksums for Windows platform entries, instead of incorrectly using the MRI source tarball checksum. The lockfile generator now fetches the correct .7z asset from the oneclick/rubyinstaller2 GitHub releases for Windows targets. #​8357 by @​jdx

Changed

• Registry: terradozer switched to GitHub fork -- The terradozer registry entry now points to github:chenrui333/terradozer (replacing the archived asdf plugin and unavailable aqua backend), and is restricted to Linux and macOS. #​8365 by @​chenrui333

New Contributors

• @​chenrui333 made their first contribution in #​8365

Full Changelog: jdx/mise@v2026.2.21...v2026.2.22