Settings

Settings change how mise itself behaves, such as how many jobs run at once, how downloads are verified and how tasks print output. Set them with mise settings or under [settings] in a config file. Variables for your own programs belong in [env] instead.

Change a setting

mise settings set writes to the global config, ~/.config/mise/config.toml. Add --local to write to the project config instead, normally mise.toml (see which file mise writes to):

mise settings jobs=4          # global config
mise settings --local jobs=2  # project config
mise settings unset --local jobs  # remove the project value
mise settings add disable_hints python_multi  # append to a list setting

The same settings in TOML:

[settings]
jobs = 4

[settings.node]
compile = true # the node.compile setting

A dotted name such as node.compile is a table under [settings]. Each entry in the reference lists the setting's environment variable, usually MISE_ followed by the name in upper case with dots replaced by underscores, such as MISE_NODE_COMPILE.

To see what mise uses:

mise settings get jobs           # the value in effect here
mise settings ls                 # values set in config files, with each file
mise settings ls --all           # every setting, including defaults

Which value wins

When a setting is set in more than one place, mise uses the first of these that sets it:

1. A command-line flag, such as --jobs or --yes (see global flags)
2. The setting's environment variable, such as MISE_JOBS
3. [settings] in project config, starting with the file nearest the current directory; mise.local.toml wins over mise.toml in the same directory
4. [settings] in the global config, ~/.config/mise/config.toml
5. [settings] in the system config, /etc/mise/config.toml
6. The default

minimum_release_age_excludes is the exception: it combines the lists from every config file, and its environment variable replaces the combined list. In safe mode, mise ignores [settings] in project config.

Settings with restricted locations

Most settings work in every place listed above. Three kinds do not, and the reference marks each of them with a badge.

Global-only settings

Settings with the global only badge take effect only in the global or system config, or in their environment variable where they have one, so a repository you clone cannot set them. Most of them control what mise runs, trusts, downloads or writes on your machine, or whether it asks before acting, such as yes, trusted_config_paths, paranoid, github.credential_command, self_update.auto and shims_dir. In project config, mise ignores them and prints a warning:

mise WARN  yes in non-global config /home/me/app/mise.toml is ignored for security reasons

mise settings --local and mise settings add --local refuse these settings. Drop --local to write them to the global config, or use the environment variable.

Settings read before config files

Settings with the miserc badge decide which config files mise loads, so mise reads them before any mise.toml: env, auto_env, env_conf_d, ceiling_paths, ignored_config_paths, override_config_filenames and override_tool_versions_filenames. Set them in a .miserc.toml file, without a [settings] table, or with their environment variables. env also has the -E/--env flag.

.miserc.toml

env = ["development"]

Under [settings] in mise.toml or the global config they have no effect. mise settings refuses them and names the miserc.toml file or variable to use, so edit .miserc.toml yourself.

Environment-only settings

Settings with the env only badge name the config files themselves, so they work only as environment variables: default_config_filename, default_tool_versions_filename, global_config_file, global_config_root and system_config_file. mise settings refuses them, and mise ignores them, with a warning, in every config file, including the global one. A .miserc.toml ignores them without a warning.

Environment variables that are not settings, such as MISE_DATA_DIR, are listed in MISE_* variables.

Reference

Groups: age, aqua, cargo, conda, dotfiles, dotnet, erlang, forgejo, github, github_relay, gitlab, go, history, hook_env, java, node, npm, oci, otel, packslip, prune, pypi, python, ruby, rust, sandbox, self_update, shims, skills, sops, spm, status, swift, system_packages, task, tool_update, upgrade, write_targets, zig

activate_aggressive

Keep mise's tool directories ahead of PATH entries added after mise activate.

• Type: boolean
• Default: false
• Environment variable: MISE_ACTIVATE_AGGRESSIVE

By default, a directory added to PATH after mise activate takes precedence over mise's tools. With this in ~/.zshrc:

eval "$(mise activate zsh)"
PATH="/some/other/python:$PATH"

python runs /some/other/python, not the version from mise.toml. Move mise activate to the end of your shell startup file, or set activate_aggressive = true to keep mise's tools first.

activate_shims

Let mise activate add the shims directories to PATH for auto-install and lazy tools.

• Type: boolean
• Default: true
• Environment variable: MISE_ACTIVATE_SHIMS

Set to false to keep the user and system shims directories out of PATH during mise activate and later prompts. Restart your shell after changing it.

Shims provide missing-version auto-installation and first-use installation of lazy tools, so without them those commands may not be found; run mise install or mise exec instead. Installed tools still get their own bin directories on PATH.

Command wrappers, such as cargo through mr-boxington, use a separate command-wrappers/bin directory and stay active. mise activate --shims adds shims whatever this is set to. See Shims.

age

age.identity_files

Age identity files to try when decrypting.

• Type: path[]
• Default: unset
• Environment variable: MISE_AGE_IDENTITY_FILES (separated by : (; on Windows))

Used for age-encrypted [env] values and encrypted dotfiles. See Decryption identities for the order mise tries identities in.

age.key_file

Age private key file used to decrypt and as the default recipient when encrypting.

• Type: path
• Default: "~/.config/mise/age.txt"
• Environment variable: MISE_AGE_KEY_FILE

Used for age-encrypted [env] values and encrypted dotfiles. See Decryption identities.

age.ssh_identity_files

SSH private keys to try when decrypting age values.

• Type: path[]
• Default: unset
• Environment variable: MISE_AGE_SSH_IDENTITY_FILES (separated by : (; on Windows))

Used for age-encrypted [env] values and encrypted dotfiles. See Decryption identities for the order mise tries identities in.

age.strict

Fail when an [env] age value cannot be decrypted, instead of skipping it.

• Type: boolean
• Default: true
• Environment variable: MISE_AGE_STRICT

Decryption fails when no identity is found, none can decrypt the value, or the payload is invalid. Set to false to skip those variables and resolve the rest of the environment.

all_compile

Compile Node.js, Python, Ruby and Erlang from source instead of using precompiled builds.

• Type: boolean
• Default: true on Alpine and NixOS, false elsewhere
• Environment variable: MISE_ALL_COMPILE

Sets the default for node.compile, python.compile, ruby.compile and erlang.compile; a tool's own setting takes precedence. Other tools are not affected.

The automatic true on Alpine and NixOS is deprecated. Installs that rely on it have warned since mise 2026.8.0, and from mise 2027.8.0 the default is false everywhere. Set all_compile = true to keep building from source.

always_keep_downloaddeprecated

Keep downloaded archives and sources after installing, for debugging.

• Type: boolean
• Default: false
• Environment variable: MISE_ALWAYS_KEEP_DOWNLOAD
• Deprecated: Finished downloads are kept in the download cache instead; see download_cache.

mise keeps the files under ~/.local/share/mise/downloads so you can inspect them while debugging a backend or plugin. Downloads that go through mise's HTTP client are kept in download_cache instead, under their own names, so this is only needed for files an asdf plugin script downloads itself.

always_keep_install

Keep a failed installation's partial install directory and downloads, for debugging.

• Type: boolean
• Default: false
• Environment variable: MISE_ALWAYS_KEEP_INSTALL

aqua

aqua.baked_registry

Use the aqua registry built into mise.

• Type: boolean
• Default: true
• Environment variable: MISE_AQUA_BAKED_REGISTRY

Set to false to resolve aqua packages only from aqua.registries, or, when none are configured, from the official registry downloaded from GitHub.

aqua.cosign

Verify Cosign signatures for aqua packages that declare them.

• Type: boolean
• Default: true
• Environment variable: MISE_AQUA_COSIGN

mise verifies the signatures itself; no cosign binary is needed.

aqua.github_attestations

Verify GitHub artifact attestations for aqua packages that declare them.

• Type: boolean
• Default: true
• Environment variable: MISE_AQUA_GITHUB_ATTESTATIONS

Has no effect when the global github_attestations setting is false.

aqua.minisign

Verify Minisign signatures for aqua packages that declare them.

• Type: boolean
• Default: true
• Environment variable: MISE_AQUA_MINISIGN

mise verifies the signatures itself; no minisign binary is needed.

aqua.registries

Aqua registries to search, in order, before the baked-in registry.

• Type: string[]
• Default: unset
• Environment variable: MISE_AQUA_REGISTRIES (comma-separated)

Each entry is a repository URL, a URL to a registry.yaml file, an absolute file:// URL, or a path relative to the config file that sets it. For a repository or directory, mise reads registry.yaml at its root, or registry.yml when that is missing.

[settings]
aqua.registries = ["https://github.com/my-org/aqua-registry", "registry.yaml"]

Relative paths resolve only from config files, so a path in MISE_AQUA_REGISTRIES must be an absolute file:// URL. mise settings writes the value into a config file, so a relative path set that way resolves against that file's config root ($HOME for the global config).

While aqua.baked_registry is on, the baked-in registry is the fallback for packages these registries do not define. With registry_floating, mise also downloads the official aqua registry and checks it after the configured registries and before the baked-in one, falling back to the baked-in registry if the download fails. Downloaded registries are cached for aqua.registry_cache_ttl; file:// registries are read directly. See Custom registry.

aqua.registry_cache_ttl

How long a downloaded aqua registry stays fresh before mise downloads it again.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "1w"
• Environment variable: MISE_AQUA_REGISTRY_CACHE_TTL

Set to 0s to download remote registries every time mise loads them. Local file:// registries are always read directly.

aqua.registry_urldeprecated

URL of one aqua registry repository to search before the baked-in registry.

• Type: string
• Default: unset
• Environment variable: MISE_AQUA_REGISTRY_URL
• Deprecated: Use aqua.registries instead.

When both are set, aqua.registries takes precedence.

aqua.slsa

Verify SLSA provenance for aqua packages that declare it.

• Type: boolean
• Default: true
• Environment variable: MISE_AQUA_SLSA

Has no effect when the global slsa setting is false.

arch

Architecture of the precompiled binaries mise downloads.

• Type: string
• Default: host architecture
• Environment variable: MISE_ARCH

x86_64 and amd64 mean x64, and aarch64 means arm64; other values, such as arm, loongarch64 or riscv64, are used as written. Set it to install binaries for another architecture, for example on a machine that runs x64 binaries under emulation.

auto_envmiserc

Automatically enable platform config environments (unix, {os}, {os}-{arch}).

• Type: boolean
• Default: false (true from mise 2027.6.0)
• Environment variable: MISE_AUTO_ENV
• Set in: a .miserc.toml file or MISE_AUTO_ENV. mise reads it before config files load, so [settings] in mise.toml has no effect. See settings read before config files.

When enabled, mise treats these as active config environments, in addition to any explicit MISE_ENV: unix on Unix-family platforms, the OS name (linux, macos or windows), and {os}-{arch}, such as macos-arm64 or windows-x64. Architecture names follow mise's spelling: x86_64 becomes x64 and aarch64 becomes arm64.

Config files such as mise.windows.toml, mise/config.macos-arm64.toml or mise.unix.toml then load automatically, and matching mise.<env>.lock lockfiles are selected. Platform environments rank below explicit MISE_ENV entries: unix < {os} < {os}-{arch} < explicit MISE_ENV entries. They do not change the {{ mise_env }} template variable or the MISE_ENV variable passed to subprocesses.

Set it to false to keep today's behavior after the default changes. See Platform environments.

auto_install

Install missing tools automatically when a command needs them.

• Type: boolean
• Default: true
• Environment variable: MISE_AUTO_INSTALL

When false, mise never installs automatically: this also turns off exec_auto_install, not_found_auto_install and task.run_auto_install. To skip only some tools, use auto_install_disable_tools. See Auto-install mechanisms.

auto_install_disable_tools

Tools that automatic installs skip, such as node.

• Type: string[]
• Default: unset
• Environment variable: MISE_AUTO_INSTALL_DISABLE_TOOLS (comma-separated)

Applies to every automatic install, such as from mise exec, mise run or the command-not-found handler. Install these tools yourself with mise install.

auto_updatedeprecatedglobal only

Old name for self_update.auto.

• Type: boolean
• Default: false
• Environment variable: MISE_AUTO_UPDATE
• Set in: global or system config, or MISE_AUTO_UPDATE. Ignored, with a warning, in project config. See global-only settings.
• Deprecated: Use self_update.auto instead.

mise still reads this setting and MISE_AUTO_UPDATE when self_update.auto is not set.

auto_update_check_durationdeprecatedglobal only

Old name for self_update.check_duration.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "7d"
• Environment variable: MISE_AUTO_UPDATE_CHECK_DURATION
• Set in: global or system config, or MISE_AUTO_UPDATE_CHECK_DURATION. Ignored, with a warning, in project config. See global-only settings.
• Deprecated: Use self_update.check_duration instead.

mise still reads this setting and MISE_AUTO_UPDATE_CHECK_DURATION when self_update.check_duration is not set.

cache_prune_age

Delete cache files that have not been accessed for this long.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "30d"
• Environment variable: MISE_CACHE_PRUNE_AGE

mise deletes such files from time to time on its own, and mise cache prune uses the same age. Set to 0s to keep cache files indefinitely; both the automatic sweep and mise cache prune then skip pruning.

This covers the cache directories only. Cached environments expire by env_cache_ttl instead. See Cache auto-pruning.

cargo

cargo.binstall

Install Cargo tools from cargo-binstall's prebuilt binaries when cargo-binstall is installed.

• Type: boolean
• Default: true
• Environment variable: MISE_CARGO_BINSTALL

mise uses a cargo-binstall installed through mise or found on PATH, and runs cargo install when it has no prebuilt binary. A prebuilt binary ignores your Cargo build configuration, so set this to false when that configuration must apply. Install cargo-binstall with mise use -g cargo-binstall. See How mise installs a crate.

cargo.binstall_native

Use mise's own prebuilt-binary installer for Cargo tools when cargo-binstall is not installed.

• Type: boolean
• Default: unset
• Environment variable: MISE_CARGO_BINSTALL_NATIVE

The installer downloads binaries described by package.metadata.binstall in the crate's Cargo.toml, or named the usual way in the GitHub releases of the crate's repository. It runs cargo install instead when it finds no binary or the install uses Cargo build options that would change the result.

• true: try this installer before cargo install.
• false: never use it.
• unset: do not use it. From mise 2027.1.0, mise warns when a crate could have been installed this way, and from mise 2027.7.0 unset means true.

Setting cargo.binstall to false turns this installer off too.

cargo.binstall_only

Require prebuilt binaries from cargo-binstall instead of falling back to cargo install.

• Type: boolean
• Default: false
• Environment variable: MISE_CARGO_BINSTALL_ONLY

Installs fail when cargo-binstall is missing or turned off, has no prebuilt binary, or a tool option such as features needs cargo install. Tools from a Git source are unaffected; they always build with cargo install --git.

cargo.binstall_quickinstall

Let cargo-binstall download third-party artifacts from cargo-quickinstall.

• Type: boolean
• Default: false
• Environment variable: MISE_CARGO_BINSTALL_QUICKINSTALL

By default, mise passes --disable-strategies compile,quick-install to cargo-binstall, so it uses only artifacts that the crate's authors publish, never cargo-quickinstall builds. With true, mise passes --disable-strategies compile instead. mise's own installer (cargo.binstall_native) never uses quickinstall.

cargo.registry_name

Cargo registry to install crates from instead of crates.io.

• Type: string
• Default: unset
• Environment variable: MISE_CARGO_REGISTRY_NAME

The name of an alternate registry defined in your Cargo configuration ([registries.<name>]), such as a private mirror. mise passes it to cargo install as --registry, and does not use its own prebuilt-binary installer while it is set.

ceiling_pathsmiserc

Directories where mise stops searching parent directories for config files.

• Type: path[]
• Default: []
• Environment variable: MISE_CEILING_PATHS (separated by : (; on Windows))
• Set in: a .miserc.toml file or MISE_CEILING_PATHS. mise reads it before config files load, so [settings] in mise.toml has no effect. See settings read before config files.

By default, mise looks for config files in the current directory and every parent up to the filesystem root. The search stops at a ceiling directory, which is not searched itself: with MISE_CEILING_PATHS=/home/user, /home/user/projects/app/mise.toml loads but /home/user/mise.toml does not. This matches Git's GIT_CEILING_DIRECTORIES.

mise settings and mise settings add refuse this setting, because mise reads it before config files load; put it in a .miserc.toml file or the environment variable instead.

color

Use color in mise's terminal output.

• Type: boolean
• Default: true
• Environment variable: MISE_COLOR

color_theme

Color theme for interactive prompts, such as the task picker in mise run.

• Type: string
• Default: "default"
• Environment variable: MISE_COLOR_THEME
• Choices:
  • auto: base16 on light terminals (detected from COLORFGBG), charm otherwise
  • default: same as auto
  • charm: suits dark terminals
  • base16: suits light terminals
  • catppuccin
  • dracula

With colors off (color = false, NO_COLOR or CLICOLOR=0), prompts are unstyled whatever this is set to.

conda

conda.channel

Channel for conda: tools that do not set their own.

• Type: string
• Default: "conda-forge"
• Environment variable: MISE_CONDA_CHANNEL

The package and all of its dependencies must come from this one channel. Override it for one tool with the channel tool option.

default_config_filenameenv only

Extra project config filename mise reads, and the name it gives new config files.

• Type: string
• Default: "mise.toml"
• Environment variable: MISE_DEFAULT_CONFIG_FILENAME
• Set in: MISE_DEFAULT_CONFIG_FILENAME only. mise reads it before config files load and ignores it in any config file. See environment-only settings.

mise still reads mise.toml and the other standard names. To move the global config, use global_config_file; to replace the list of names mise reads, use override_config_filenames.

default_tool_versions_filenameenv only

Extra filename mise reads as a .tool-versions file.

• Type: string
• Default: ".tool-versions"
• Environment variable: MISE_DEFAULT_TOOL_VERSIONS_FILENAME
• Set in: MISE_DEFAULT_TOOL_VERSIONS_FILENAME only. mise reads it before config files load and ignores it in any config file. See environment-only settings.

.tool-versions files are still read; to stop reading them, use override_tool_versions_filenames.

disable_backends

Backends mise ignores when resolving and installing tools, such as asdf or pypi.

• Type: string[]
• Default: []
• Environment variable: MISE_DISABLE_BACKENDS (comma-separated)

Tools already installed with a disabled backend stay on disk and work again once you re-enable it. A vfox backend plugin can be disabled by its plugin name.

disable_default_registry

Stop mapping short names such as php to the asdf and vfox plugins listed in the registry.

• Type: boolean
• Default: false
• Environment variable: MISE_DISABLE_DEFAULT_REGISTRY

disable_hints

Hints to stop showing, by ID; * turns off every hint.

• Type: string[]
• Default: []
• Environment variable: MISE_DISABLE_HINTS (comma-separated)

mise shows each hint once and records it in $MISE_STATE_DIR/hints. To turn one off before it appears, or all of them:

mise settings add disable_hints python_multi
mise settings add disable_hints '*'

Hint IDs include tools_missing, python_multi, python_precompiled, ruby_precompiled, upgrade_auto_prune and skills.

disable_tools

Tools mise ignores even when a config file lists them.

• Type: string[]
• Default: []
• Environment variable: MISE_DISABLE_TOOLS (comma-separated)

Ignored when enable_tools is set.

disable_update_warning

Suppress warnings when a newer mise version is available.

• Type: boolean
• Default: false
• Environment variable: MISE_DISABLE_UPDATE_WARNING

Hides the update notice in mise version, mise --version and mise doctor. Other warnings are unaffected. It does not turn off mise self-update or automatic updates with self_update.auto.

dotfiles

dotfiles.default_mode

Mode for [dotfiles] entries that do not set mode.

• Type: string
• Default: "symlink"
• Environment variable: MISE_DOTFILES_DEFAULT_MODE
• Choices:
  • symlink: link the target to its source
  • symlink-each: create directories and link each file in them
  • copy: copy the source to the target
  • template: render the source as a template

Applies to entries without mode, including string entries such as "~/.vimrc" = "vimrc", and to mise dot add without --mode. track and absent cannot be the default; set them on each entry. An unsupported value falls back to symlink with a warning. See Modes.

dotfiles.relative_symlinks

Create dotfile symlinks with relative targets instead of absolute ones.

• Type: boolean
• Default: false
• Environment variable: MISE_DOTFILES_RELATIVE_SYMLINKS

Applies to symlink and symlink-each entries; an entry's relative key overrides it. Relative links keep working when the home directory is mounted at a different path on another machine or the tree is moved, as long as the target and source keep their positions relative to each other. Ignored on Windows, where directory links are junctions, which cannot be relative. See relative.

dotfiles.root

Directory that holds dotfile sources for entries without a source.

• Type: path
• Default: "~/.dotfiles"
• Environment variable: MISE_DOTFILES_ROOT

~/.zshrc reads its source from <root>/.zshrc, and mise dot add saves new sources here. Relative [dotfile_groups] roots and the relative keys of destination-variant entries also resolve against it. See Whole-file entries.

dotnet

dotnet.cli_telemetry_optout

Set DOTNET_CLI_TELEMETRY_OPTOUT to opt out of .NET CLI telemetry.

• Type: boolean
• Default: unset
• Environment variable: MISE_DOTNET_CLI_TELEMETRY_OPTOUT

true sets DOTNET_CLI_TELEMETRY_OPTOUT=1 and false sets it to 0. When unset, mise leaves the variable alone and .NET uses its own default.

dotnet.dotnet_root

Shared directory that every .NET SDK version installs into.

• Type: path
• Default: $DOTNET_ROOT when set, otherwise ~/.local/share/mise/dotnet-root
• Environment variable: MISE_DOTNET_ROOT

SDK versions install side by side here, matching .NET's own multi-version layout. Ignored when dotnet.isolated is true.

dotnet.isolated

Install each .NET SDK version in its own isolated directory.

• Type: boolean
• Default: false
• Environment variable: MISE_DOTNET_ISOLATED

With true, each SDK version installs under mise's installs directory like other tools, and dotnet --list-sdks shows only the active one. With false, every version shares dotnet.dotnet_root and dotnet --list-sdks lists all of them.

dotnet.package_flagsdeprecated

Flags for every dotnet: tool; the only flag, prerelease, includes prereleases.

• Type: string[]
• Default: []
• Environment variable: MISE_DOTNET_PACKAGE_FLAGS (comma-separated)
• Deprecated: Use the prerelease = true tool option or the global prereleases setting instead.

Because it applies to every tool, prerelease here also overrides a tool's own prerelease = false.

dotnet.registry_url

NuGet service index used to discover dotnet tool versions.

• Type: URL
• Default: "https://api.nuget.org/v3/index.json"
• Environment variable: MISE_DOTNET_REGISTRY_URL

Installation runs dotnet tool install, which reads its own NuGet.Config and credentials. Configure a private feed there as well; this setting does not add an installation source to the dotnet CLI.

download_cache

Reuse finished downloads instead of fetching them again.

• Type: boolean
• Default: true
• Environment variable: MISE_DOWNLOAD_CACHE

mise keeps finished downloads in $MISE_CACHE_DIR/downloads-cas, named by their hash, and uses one again in two cases:

• The server confirms it is unchanged. The next request for the same URL carries the ETag or Last-Modified value the server sent, and a 304 Not Modified answer means the kept file is used instead of a new download. Servers that send no validator are not cached.
• A tool pinned its checksum, in its options or in mise.lock. The kept file is used with no request at all, even if the URL changed.

The http, github, aqua and packslip backends and the core tools' precompiled archives pin and install from the stored file, linked into place where the filesystem allows, so the archive takes no extra space and is not copied; across devices it is copied. The core tools pin with the checksum in mise.lock. Node's source tarball is kept the same way and compiled each time. Other source builds, such as Ruby and Python through ruby-build and python-build, download their own sources, which are not kept. Every other download that goes through mise's HTTP client uses the first case and is copied into place.

With locked or paranoid, only downloads with a pinned checksum are reused or kept, since only those are checked afterwards. Restoring downloads-cas in CI then gives a cache you can trust, which a restored install directory is not.

A kept file is hashed again before it is used, and one that no longer matches is dropped and downloaded again. The recorded hash lives beside the file, so this catches damage but does not stop someone who can write the cache from replacing both. A pinned checksum is always checked after the download, so pin one if the cache is shared. The cache holds up to download_cache_max_size; the least recently used entries go first. Extracted files are not covered; see Restored caches and installed tools.

download_cache_max_size

Maximum total size of the download cache, such as 500MB or 10GiB.

• Type: string
• Default: "2GiB"
• Environment variable: MISE_DOWNLOAD_CACHE_MAX_SIZE

After storing a download, mise removes the least recently used ones until the cache in $MISE_CACHE_DIR/downloads-cas fits. A download used in the last ten minutes is kept, since another install may be placing it. 0 means no limit. See download_cache.

enable_tools

Allowlist of configured tools mise uses; other tools are ignored.

• Type: string[]
• Default: unset
• Environment variable: MISE_ENABLE_TOOLS (comma-separated)

When unset, mise uses every configured tool except those in disable_tools. Once set, this list is the complete allowlist and disable_tools is ignored. An empty list ([], or MISE_ENABLE_TOOLS= with nothing after it) disables every tool.

envmiserc

Config environments to load, such as development for mise.development.toml.

• Type: string[]
• Default: []
• Environment variable: MISE_ENV (comma-separated)
• Set in: a .miserc.toml file or MISE_ENV. mise reads it before config files load, so [settings] in mise.toml has no effect. See settings read before config files.

Selects which config environments load, so mise.development.toml applies only when development is set. Separate several with commas, such as MISE_ENV=ci,test; later ones take precedence. The -E/--env flag sets it for one command.

env_cacheexperimental

Cache computed environments on disk for nested mise commands.

• Type: boolean
• Default: false
• Environment variable: MISE_ENV_CACHE

Caches environment variables and PATH so nested commands such as mise exec -- mise env skip recomputing them. Entries expire after env_cache_ttl or when config files, tool versions, settings, or files that env plugins watch change. Edits to dotenv files or _.source scripts may not invalidate an entry; set MISE_ENV_CACHE=0 for a command that must recompute. Configurations with secrets (an age value, a sops-encrypted file or redact = true) are never cached. See Environment cache.

env_cache_ttl

How long a cached environment stays valid.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "1h"
• Environment variable: MISE_ENV_CACHE_TTL

Entries are also invalidated when config files, tool versions, settings or watched files change.

env_conf_dmiserc

Enable environment-specific filenames in conf.d directories.

• Type: boolean
• Default: false (true from mise 2027.8.10)
• Environment variable: MISE_ENV_CONF_D
• Set in: a .miserc.toml file or MISE_ENV_CONF_D. mise reads it before config files load, so [settings] in mise.toml has no effect. See settings read before config files.

With this on, a conf.d fragment with an environment in its name loads only when that environment is active: tools.development.toml loads only with development, and tools.development.local.toml is its local variant. It applies to every conf.d directory: mise/conf.d, .mise/conf.d, .config/mise/conf.d, ~/.config/mise/conf.d and /etc/mise/conf.d. With it off, every non-hidden TOML file in conf.d loads.

Dots in the names of unconditional fragments are deprecated; rename node.tools.toml to node-tools.toml before the default changes. See conf.d environments.

env_file

Dotenv file name to load from the current directory and each parent directory.

• Type: path
• Default: unset
• Environment variable: MISE_ENV_FILE

mise loads every file with this name, such as .env, between the filesystem root and the current directory. When a variable appears in more than one file, the file nearest the current directory wins. An absolute path loads that one file. For a dotenv file that belongs to one project, use _.file in mise.toml instead.

env_shell_expand

Expand shell-style variables such as $FOO and ${BAR:-default} in [env] values.

• Type: boolean
• Default: true
• Environment variable: MISE_ENV_SHELL_EXPAND

[env]
FOO = "hello"
BAR = "$FOO-world"         # "hello-world"
BAZ = "${FOO}_suffix"      # "hello_suffix"
QUX = "${UNDEF:-fallback}" # "fallback"

Expansion runs after Tera templates render, so both syntaxes can be mixed. An undefined variable stays as written and logs a warning; write ${MISSING:-} to expand it to an empty string without one. Set to false to leave $ sequences untouched. See Shell-style variable expansion.

erlang

erlang.compile

Compile Erlang from source instead of using a precompiled build.

• Type: boolean
• Default: unset
• Environment variable: MISE_ERLANG_COMPILE

true always builds from source with kerl. false uses only precompiled builds and fails when none exists for the platform. When unset, all_compile decides; if that is unset too, mise uses a precompiled build when one is available and builds from source otherwise.

erlang.precompiled_os

Ubuntu release whose precompiled Erlang build from builds.hex.pm mise installs on Linux.

• Type: string
• Default: unset
• Environment variable: MISE_ERLANG_PRECOMPILED_OS
• Choices:
  • ubuntu-20.04
  • ubuntu-22.04
  • ubuntu-24.04
  • ubuntu-26.04

Applies to glibc Linux targets, including mise lock for Linux platforms from another OS, which otherwise assumes ubuntu-24.04. When unset on Linux, mise derives it from $ImageOS (GitHub Actions) or /etc/os-release, and uses precompiled builds automatically only for Ubuntu 20.04, 22.04 and 24.04. Set it to ubuntu-26.04 on that release, or to one of these Ubuntu releases on another glibc distribution to use that release's build; other values are rejected. musl Linux always builds from source.

exec_auto_install

Install missing tools automatically when you run mise exec.

• Type: boolean
• Default: true
• Environment variable: MISE_EXEC_AUTO_INSTALL

Has no effect when auto_install is false.

experimental

Enable experimental features, which may change or be removed in any release.

• Type: boolean
• Default: false
• Environment variable: MISE_EXPERIMENTAL

Turns on features that are still being designed. An experimental feature can change or disappear in any release; once it leaves experimental, changes follow the normal deprecation process. A feature's docs say when it needs this setting.

Some new behavior also ships behind this flag before it becomes the default, so enabling it helps catch problems early. If something breaks after you enable it, check whether it still happens with experimental = false, then open an issue.

fetch_remote_versions_cache

How long a tool's cached list of available versions stays fresh.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "1h"
• Environment variable: MISE_FETCH_REMOTE_VERSIONS_CACHE

mise outdated, mise upgrade, mise ls-remote, mise lock and mise latest fetch the list again once it is older than this, 1 hour by default.

When this is not set, 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: 23 hours by default, 5 hours for a tool with minimum_release_age = "6h", and never less than 1 hour or more than 24 hours. A release newer than the list could not be picked before it reached that age anyway. This applies only to lists that date every version; others are refetched after 1 hour. Setting this value applies it to every command.

Commands that prefer offline data, such as shims, mise activate, mise exec, mise env and mise ls, use the cached list whatever its age, as does every command when prefer_offline is on. The same duration controls when remote include fragments that point at a branch or tag are refreshed. See When mise refreshes version lists.

fetch_remote_versions_timeout

Timeout for looking up a tool's available versions.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "20s"
• Environment variable: MISE_FETCH_REMOTE_VERSIONS_TIMEOUT

Applies to HTTP requests to version sources and to version-listing commands that backends run, such as go list or an asdf plugin's scripts. A bare number is seconds.

Commands that prefer offline data, such as shims, shell activation, mise exec, mise env and mise ls, cap this at 3 seconds and do not retry, so they do not hang when the network is down. mise lock, mise ls-remote, mise outdated and mise upgrade always use the full timeout.

forgejo

forgejo.credential_commandglobal only

Command that prints a Forgejo token on stdout.

• Type: string
• Default: ""
• Environment variable: MISE_FORGEJO_CREDENTIAL_COMMAND
• Set in: global or system config, or MISE_FORGEJO_CREDENTIAL_COMMAND. Ignored, with a warning, in project config. See global-only settings.

mise runs the command with the default inline shell (unix_default_inline_shell_args or windows_default_inline_shell_args) and uses its trimmed output as the token. The command receives MISE_CREDENTIAL_HOST, the host that needs a token, so one command can serve several self-hosted Forgejo servers, and MISE_CREDENTIAL_PROVIDER=forgejo. mise tries it right after the token environment variables; if it fails or prints nothing, mise moves on to the next source. It does not need forgejo.use_git_credentials.

~/.config/mise/config.toml

[settings.forgejo]
credential_command = 'op read "op://Private/Forgejo Token/credential"'

See Credential command and Token priority.

forgejo.fj_cli_tokens

Read Forgejo tokens that the fj CLI stores in its keys.json file.

• Type: boolean
• Default: true
• Environment variable: MISE_FORGEJO_FJ_CLI_TOKENS

See CLI logins for where mise looks for the file and Token priority for when it is used.

forgejo.use_git_credentials

Get Forgejo tokens from your Git credential helpers with git credential fill.

• Type: boolean
• Default: false
• Environment variable: MISE_FORGEJO_USE_GIT_CREDENTIALS

This reaches tokens kept by helpers such as the macOS Keychain or Windows Credential Manager. mise tries it last, after the environment variables, forgejo.credential_command, forgejo_tokens.toml and fj CLI tokens, and caches the result per host while it runs. See Git credential helpers.

github

github.credential_commandglobal only

Command that prints a GitHub token on stdout.

• Type: string
• Default: ""
• Environment variable: MISE_GITHUB_CREDENTIAL_COMMAND
• Set in: global or system config, or MISE_GITHUB_CREDENTIAL_COMMAND. Ignored, with a warning, in project config. See global-only settings.

mise runs the command with the default inline shell (unix_default_inline_shell_args or windows_default_inline_shell_args) and uses its trimmed output as the token. The command receives MISE_CREDENTIAL_HOST, the host that needs a token, so one command can serve github.com and GitHub Enterprise hosts, and MISE_CREDENTIAL_PROVIDER=github. mise tries it right after the token environment variables and before native GitHub OAuth; if it fails or prints nothing, mise moves on to the next source. It does not need github.use_git_credentials.

~/.config/mise/config.toml

[settings.github]
credential_command = 'op read "op://Private/GitHub Token/credential"'

See Credential command and Token priority.

github.gh_cli_tokens

Read GitHub tokens that the gh CLI stores in its hosts.yml file.

• Type: boolean
• Default: true
• Environment variable: MISE_GITHUB_GH_CLI_TOKENS

gh stores a token per host, so this also covers GitHub Enterprise hosts. Tokens that gh keeps in the system keyring are not in hosts.yml; see If gh keeps its token in the system keyring. See CLI logins for where mise looks for the file and Token priority for when it is used.

github.github_attestations

Verify GitHub artifact attestations for github backend tools.

• Type: boolean
• Default: true
• Environment variable: MISE_GITHUB_GITHUB_ATTESTATIONS

Attestations are checked only when this setting, the global github_attestations setting and the tool's own github_attestations option are all true; set the option to false to skip one tool. Tools with a custom api_url, such as those on GitHub Enterprise Server, are not checked, because that API has no attestations endpoint.

github.oauth_api_url

GitHub API base URL mise uses to validate native OAuth tokens.

• Type: string
• Default: "https://api.github.com"
• Environment variable: MISE_GITHUB_OAUTH_API_URL

github.oauth_auth_url

GitHub OAuth endpoint base URL for the native device flow.

• Type: string
• Default: "https://github.com/login"
• Environment variable: MISE_GITHUB_OAUTH_AUTH_URL

Change it for a GitHub Enterprise host that supports device flow.

github.oauth_cache_getglobal only

Command that prints the native GitHub OAuth refresh tokens stored by github.oauth_cache_set.

• Type: string
• Default: ""
• Environment variable: MISE_GITHUB_OAUTH_CACHE_GET
• Set in: global or system config, or MISE_GITHUB_OAUTH_CACHE_GET. Ignored, with a warning, in project config. See global-only settings.

By default mise keeps the long-lived, rotating OAuth refresh token in github-oauth-tokens.toml in its state directory, readable by anything running as your user. Set this and github.oauth_cache_set together to keep the refresh token in a password manager or keychain instead; the file then holds only the short-lived access token.

mise runs the command with the default inline shell (unix_default_inline_shell_args or windows_default_inline_shell_args) and reads the stored value from its stdout. It runs only when the access token has to be refreshed, about once every eight hours, and when mise stores a new token, not on every mise invocation. Empty output means nothing is stored yet. If the command fails when mise needs to refresh, mise skips the refresh and keeps the cached token, so a locked vault never costs you the session. While storing a new token, a failure counts as an empty store only if the cache file still holds every refresh token, since many tools fail on an entry that does not exist yet. The command gets no host, because one value holds the tokens for every host. It is stopped after 60 seconds.

See Keeping the refresh token out of the cache file.

github.oauth_cache_secure_enclaveglobal only

Keep the native GitHub OAuth refresh token behind Touch ID in the macOS Secure Enclave.

• Type: boolean
• Default: false
• Environment variable: MISE_GITHUB_OAUTH_CACHE_SECURE_ENCLAVE
• Set in: global or system config, or MISE_GITHUB_OAUTH_CACHE_SECURE_ENCLAVE. Ignored, with a warning, in project config. See global-only settings.

macOS only. mise seals the long-lived, rotating OAuth refresh token to the Secure Enclave and keeps the sealed value in github-oauth-tokens.sealed in its state directory; the cache file then holds only the short-lived access token. Unsealing needs Touch ID, so mise asks for it only when the access token has to be refreshed, about once every eight hours, and never on other invocations. The sealed value works only on this Mac and stops working if the enrolled fingerprints change, in which case mise token github --oauth authorizes again.

It needs a Mac with Touch ID and the Developer ID signed binary from mise's own releases. Other builds, such as Homebrew, and machines without Touch ID warn and keep the refresh token in the cache file. A failed or cancelled prompt never discards the cached token: mise skips the refresh and tries again later. When set, it takes precedence over github.oauth_cache_get and github.oauth_cache_set.

See Keeping the refresh token out of the cache file.

github.oauth_cache_setglobal only

Command that stores the native GitHub OAuth refresh tokens, read from its stdin.

• Type: string
• Default: ""
• Environment variable: MISE_GITHUB_OAUTH_CACHE_SET
• Set in: global or system config, or MISE_GITHUB_OAUTH_CACHE_SET. Ignored, with a warning, in project config. See global-only settings.

The counterpart of github.oauth_cache_get; set both or neither. mise writes the complete value to the command's stdin, never to its arguments, each time a refresh token is issued, because GitHub rotates it on every refresh. If the command fails, mise keeps the refresh token in the cache file instead of losing it, and warns.

~/.config/mise/config.toml

[settings.github]
oauth_cache_get = "pass show mise/github-oauth"
oauth_cache_set = "pass insert -m -f mise/github-oauth"

github.oauth_client_id

GitHub App client ID that turns on native OAuth device-flow tokens.

• Type: string
• Default: ""
• Environment variable: MISE_GITHUB_OAUTH_CLIENT_ID

With a client ID, mise creates short-lived GitHub App user access tokens through GitHub's device flow, without a private key, client secret, personal access token or credential helper. Run mise token github --oauth once to authorize; mise caches the token, reuses it for GitHub API calls and refreshes it when it can. See Native GitHub OAuth.

github.oauth_copy_code

Copy the one-time device code to the clipboard during the native GitHub OAuth device flow.

• Type: boolean
• Default: unset
• Environment variable: MISE_GITHUB_OAUTH_COPY_CODE

Only the device code is copied, never the token. mise uses pbcopy on macOS, clip.exe on Windows and WSL, and wl-copy, xclip or xsel elsewhere. If none is available the code is still printed.

When unset, mise asks whether to copy the code if it is running in a terminal. Set it to true to always copy and false to never ask. Without a terminal, nothing is copied unless it is true.

github.oauth_export_env

Environment variable that mise exports the native GitHub OAuth token under; empty turns the export off.

• Type: string
• Default: "GITHUB_TOKEN"
• Environment variable: MISE_GITHUB_OAUTH_EXPORT_ENV

When github.oauth_client_id is set and a cached or refreshable token is available, mise exports the token under this variable through mise activate, mise env and mise exec, so tools that read it, such as gh, can use it. A value set in mise's [env] takes precedence; a value already in your shell environment is replaced. Git credential helpers and Cargo do not read this variable. Set it to GH_TOKEN for gh's preferred name.

github.oauth_open_browser

Open the verification page in your browser during the native GitHub OAuth device flow.

• Type: boolean
• Default: true
• Environment variable: MISE_GITHUB_OAUTH_OPEN_BROWSER

github.oauth_scopes

OAuth scopes requested for native GitHub device-flow tokens.

• Type: string
• Default: ""
• Environment variable: MISE_GITHUB_OAUTH_SCOPES

A GitHub App user access token gets its access from the app's permissions and installations, so this usually stays empty.

github.slsa

Verify SLSA provenance for github backend tools that name a signer.

• Type: boolean
• Default: true
• Environment variable: MISE_GITHUB_SLSA

Provenance is checked only for tools that set slsa_signer_identity and slsa_signer_issuer, and only while the global slsa setting is true.

github.use_git_credentials

Get GitHub tokens from your Git credential helpers with git credential fill.

• Type: boolean
• Default: false
• Environment variable: MISE_GITHUB_USE_GIT_CREDENTIALS

This reaches tokens kept by helpers such as the macOS Keychain or Windows Credential Manager. mise tries it last, after the environment variables, github.credential_command, native GitHub OAuth, github_tokens.toml and gh CLI tokens, and caches the result per host while it runs. See Git credential helpers.

github_attestations

Verify GitHub artifact attestations for downloads whose publisher provides them.

• Type: boolean
• Default: true
• Environment variable: MISE_GITHUB_ATTESTATIONS

When false, the aqua and github backends skip attestation checks whatever aqua.github_attestations and github.github_attestations say. For precompiled Python and Ruby, this is the default that python.github_attestations and ruby.github_attestations override.

github_relay

github_relay.concurrencyglobal only

Maximum relayed GitHub requests that run at once, from 1 to 32; more requests fail instead of waiting.

• Type: integer
• Default: 8
• Environment variable: MISE_GITHUB_RELAY_CONCURRENCY
• Set in: global or system config, or MISE_GITHUB_RELAY_CONCURRENCY. Ignored, with a warning, in project config. See global-only settings.

Applies to mise ssh and mise bootstrap remote sessions started with --github-relay-read-only. See Limits.

github_relay.log_formatglobal only

Format of GitHub relay request logs and the end-of-session summary.

• Type: string
• Default: "text"
• Environment variable: MISE_GITHUB_RELAY_LOG_FORMAT
• Set in: global or system config, or MISE_GITHUB_RELAY_LOG_FORMAT. Ignored, with a warning, in project config. See global-only settings.
• Choices:
  • text
  • jsonl: one JSON event per line

--github-relay-log-format overrides it for one session. See Logging.

github_relay.log_requestsglobal only

Log each relayed GitHub request, without credentials, on this machine's stderr.

• Type: boolean
• Default: false
• Environment variable: MISE_GITHUB_RELAY_LOG_REQUESTS
• Set in: global or system config, or MISE_GITHUB_RELAY_LOG_REQUESTS. Ignored, with a warning, in project config. See global-only settings.

--github-relay-log-requests and --github-relay-no-log-requests override it for one session. The setting never turns the relay on. See Logging.

github_relay.max_durationglobal only

How long a GitHub relay lends access; 0s lasts until the session ends.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "0s"
• Environment variable: MISE_GITHUB_RELAY_MAX_DURATION
• Set in: global or system config, or MISE_GITHUB_RELAY_MAX_DURATION. Ignored, with a warning, in project config. See global-only settings.

--github-relay-max-duration overrides it for one session. See When access ends.

github_relay.request_timeoutglobal only

Time limit for one relayed GitHub request, including streaming its response.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "5m"
• Environment variable: MISE_GITHUB_RELAY_REQUEST_TIMEOUT
• Set in: global or system config, or MISE_GITHUB_RELAY_REQUEST_TIMEOUT. Ignored, with a warning, in project config. See global-only settings.

Applies to mise ssh and mise bootstrap remote sessions started with --github-relay-read-only. See Limits.

gitlab

gitlab.credential_commandglobal only

Command that prints a GitLab token on stdout.

• Type: string
• Default: ""
• Environment variable: MISE_GITLAB_CREDENTIAL_COMMAND
• Set in: global or system config, or MISE_GITLAB_CREDENTIAL_COMMAND. Ignored, with a warning, in project config. See global-only settings.

mise runs the command with the default inline shell (unix_default_inline_shell_args or windows_default_inline_shell_args) and uses its trimmed output as the token. The command receives MISE_CREDENTIAL_HOST, the host that needs a token, so one command can serve gitlab.com and self-managed GitLab hosts, and MISE_CREDENTIAL_PROVIDER=gitlab. mise tries it right after the token environment variables; if it fails or prints nothing, mise moves on to the next source. It does not need gitlab.use_git_credentials.

~/.config/mise/config.toml

[settings.gitlab]
credential_command = 'op read "op://Private/GitLab Token/credential"'

See Credential command and Token priority.

gitlab.glab_cli_tokens

Read GitLab tokens that the glab CLI stores in its config.yml file.

• Type: boolean
• Default: true
• Environment variable: MISE_GITLAB_GLAB_CLI_TOKENS

See CLI logins for where mise looks for the file and Token priority for when it is used.

gitlab.use_git_credentials

Get GitLab tokens from your Git credential helpers with git credential fill.

• Type: boolean
• Default: false
• Environment variable: MISE_GITLAB_USE_GIT_CREDENTIALS

This reaches tokens kept by helpers such as the macOS Keychain or Windows Credential Manager. mise tries it last, after the environment variables, gitlab.credential_command, gitlab_tokens.toml and glab CLI tokens, and caches the result per host while it runs. See Git credential helpers.

global_config_fileenv only

One file to use as the global config instead of the config files in ~/.config/mise.

• Type: path
• Default: unset
• Environment variable: MISE_GLOBAL_CONFIG_FILE
• Set in: MISE_GLOBAL_CONFIG_FILE only. mise reads it before config files load and ignores it in any config file. See environment-only settings.

When unset, mise reads config.toml, conf.d/*.toml and the other config files in ~/.config/mise (or MISE_CONFIG_DIR), and global writes such as mise use -g go to config.toml there. When set, mise reads and writes only this file.

global_config_rootenv only

Directory used as config_root for the global config, such as for {{config_root}} in templates.

• Type: path
• Default: $HOME
• Environment variable: MISE_GLOBAL_CONFIG_ROOT
• Set in: MISE_GLOBAL_CONFIG_ROOT only. mise reads it before config files load and ignores it in any config file. See environment-only settings.

go

go.default_packages_filedeprecated

File listing Go packages to install with every Go version.

• Type: path
• Default: "~/.default-go-packages"
• Environment variable: MISE_GO_DEFAULT_PACKAGES_FILE
• Deprecated: Default go package files are deprecated. Use tool-level postinstall hooks for packages that should be installed into every go version, or use the go: backend for CLI tools.

go.download_mirror

Base URL that mise downloads Go archives and their checksums from.

• Type: string
• Default: "https://dl.google.com/go"
• Environment variable: MISE_GO_DOWNLOAD_MIRROR

go.repo

Git repository mise lists Go versions from.

• Type: URL
• Default: "https://github.com/golang/go"
• Environment variable: MISE_GO_REPO

mise reads the repository's go* tags to find Go versions when it does not get them from the versions host; set use_versions_host = false to always list from this repository. Downloads come from go.download_mirror.

go.set_gobin

Set GOBIN so go install puts binaries in the active Go version's directory.

• Type: boolean
• Default: unset
• Environment variable: MISE_GO_SET_GOBIN

When unset, mise sets GOBIN to the active Go version's bin directory unless GOBIN is already set in your environment. true always sets it, replacing your GOBIN. false never sets it, so go install uses your own GOBIN or Go's default, ${GOPATH:-$HOME/go}/bin.

go.set_gopathdeprecated

Set GOPATH to the packages directory inside the active Go install.

• Type: boolean
• Default: false
• Environment variable: MISE_GO_SET_GOPATH
• Deprecated: Set GOPATH in [env] instead. When true, this setting still sets GOPATH to the Go install's packages directory.

go.set_goroot

Set GOROOT to the active Go version's install directory.

• Type: boolean
• Default: true
• Environment variable: MISE_GO_SET_GOROOT

go.skip_checksum

Skip SHA-256 verification of Go downloads.

• Type: boolean
• Default: false
• Environment variable: MISE_GO_SKIP_CHECKSUM

gpg_verify

Verify OpenPGP signatures of Node.js and Swift downloads.

• Type: boolean
• Default: unset
• Environment variable: MISE_GPG_VERIFY

Sets the default for node.gpg_verify and swift.gpg_verify; a tool's own setting takes precedence. mise checks signatures itself, so no gpg binary is needed. When unset, mise verifies the signed SHASUMS256.txt whenever node.verify checks a Node.js download, and Swift downloads on Linux. Set to false to skip both.

history

history.allow_plaintext_historyglobal only

Allow publishing or applying history that holds plaintext copies of files now marked for encryption, or publishing versions that look like they contain secrets.

• Type: boolean
• Default: false
• Environment variable: MISE_HISTORY_ALLOW_PLAINTEXT_HISTORY
• Set in: global or system config, or MISE_HISTORY_ALLOW_PLAINTEXT_HISTORY. Ignored, with a warning, in project config. See global-only settings.

By default, the history watcher, mise dot sync and mise dot pull refuse to publish or apply history in which a file now marked for encryption was once saved in plain text, or to publish saved versions with lines that look like secrets, such as export API_TOKEN=.... With true, they skip those checks, so those older versions can reach this machine or the setup repository. New saves still follow each file's encryption policy. For a single publish, run mise dot sync --allow-plaintext-history instead. See Allow plaintext history.

history.describe_commandglobal only

Command, such as an AI agent, that writes the description of each checkpoint the history watcher saves.

• Type: string
• Default: ""
• Environment variable: MISE_HISTORY_DESCRIBE_COMMAND
• Set in: global or system config, or MISE_HISTORY_DESCRIBE_COMMAND. Ignored, with a warning, in project config. See global-only settings.

mise saves the checkpoint first, then runs the command once with a JSON object on stdin: uuid, trigger, the computed description, the changed paths (added, modified, removed) and a unified diff of changed unencrypted files, cut at 64 KiB. The line the command prints, up to 200 characters, replaces the computed description. If the command fails, prints nothing, or runs longer than 30 seconds, the computed description stays. Leave it empty to keep computed descriptions.

The diff is sent to the command. Excluded files are never named, and encrypted contents are never sent. See Descriptions from an agent.

history.enabled

Record Git checkpoints of tracked files around bootstrap operations and on explicit saves.

• Type: boolean
• Default: true
• Environment variable: MISE_HISTORY_ENABLED

Once you track files, or history already exists, mise bootstrap and mise bootstrap <part> apply record a checkpoint before and after they change anything, and mise dot save records one on demand. Dry runs never record. Checkpoints live in $MISE_STATE_DIR/history/repo.git; browse them with mise dot history.

Set to false to stop recording; existing checkpoints are kept. See Saving.

history.fetch_interval

How often the history watcher fetches from the setup repository.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "15m"
• Environment variable: MISE_HISTORY_FETCH_INTERVAL

Values below one second count as one second. To stop automatic fetching, set history.sync to manual.

history.notify

Show a desktop notification when a sync conflict pauses sharing.

• Type: boolean
• Default: true
• Environment variable: MISE_HISTORY_NOTIFY

mise notifies once, when conflicts first pause sharing for the setup; retries stay silent until sharing recovers. Other problems, such as a watcher that cannot save, appear only in mise doctor and mise dot status. A missing or failing notifier never holds up history or sync.

Linux needs notify-send. On macOS, the first notification asks for permission, so mise does not appear in System Settings > Notifications until then; run mise dot notify to send a test and get the prompt now. Unofficial macOS builds, such as Homebrew's, never show notifications and warn when you connect a setup repository. Other platforms only log the conflict. See Conflict notifications.

history.sync

What the history watcher shares with a connected setup repository on its own.

• Type: string
• Default: "sync"
• Environment variable: MISE_HISTORY_SYNC
• Choices:
  • sync: publish saves, fetch periodically and apply incoming changes
  • fetch-only: fetch periodically and never publish; apply only when you run mise dot pull
  • manual: no automatic network activity; mise dot sync publishes and fetches, and mise dot pull applies, when you run them

mise dot origin set asks for a mode when you connect a repository, or takes it from --sync. In sync mode, mise publishes at most every history.sync_interval after a save and fetches every history.fetch_interval; failures back off from one minute up to an hour, and local saves continue. A conflict pauses publishing and applying for the whole setup until you resolve it, while local saves and fetches go on. mise dot sync and mise dot pull run on request in every mode, but nothing is ever published in fetch-only mode.

Applying incoming changes never runs mise bootstrap, installs packages or renders templates. When incoming configuration changes what this machine declares, mise dot status tells you to run mise bootstrap. See Choose a sync mode.

history.sync_interval

Minimum time between automatic publishes to the setup repository after a save.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "5m"
• Environment variable: MISE_HISTORY_SYNC_INTERVAL

history.watch.debounce

How long a changed file must stay unchanged before the history watcher saves it.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "2s"
• Environment variable: MISE_HISTORY_WATCH_DEBOUNCE

A file that keeps changing gets a longer interval of its own, up to history.watch.max_interval, without delaying other files.

history.watch.max_interval

Longest save interval the history watcher uses for a file that changes constantly.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "24h"
• Environment variable: MISE_HISTORY_WATCH_MAX_INTERVAL

A file that keeps being rewritten has its own save interval doubled, up to this value, so it is still saved, ever more rarely; other files are never delayed. A settled file is saved promptly again, and a sustained quiet period resets its interval. mise never excludes a file or switches it to manual saving on its own: exclude logs, caches and databases with mise dot exclude, or track a configuration file that changes constantly with autosave = false and save it with mise dot save. See Adaptive scheduling.

history.watch.reconcile

How often the history watcher rescans all tracked files for changes it missed.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "10m"
• Environment variable: MISE_HISTORY_WATCH_RECONCILE

Set to 0s to turn off periodic rescans; the watcher still rescans at startup and when configuration changes.

hook_env

hook_env.cache_ttl

How long the shell hook reuses its last config file check, for slow filesystems such as NFS.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "0s"
• Environment variable: MISE_HOOK_ENV_CACHE_TTL

The shell hook checks config files at every prompt, which can be slow on a network filesystem with a cold cache. A positive value such as 5s reuses the last check for that long; 0s checks every time. While a check is reused, a newly created config file goes unnoticed until the time runs out; mise hook-env --force skips the cache. See Slow shell prompts.

hook_env.chpwd_only

Run the shell hook's full config check only when you change directories, not at every prompt.

• Type: boolean
• Default: false
• Environment variable: MISE_HOOK_ENV_CHPWD_ONLY

This cuts filesystem work on slow filesystems such as NFS. Changes to config files take effect after your next cd; mise hook-env --force runs a full check. See Slow shell prompts.

http_download_timeout

Total time allowed to download one file, including retries.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "30m"
• Environment variable: MISE_HTTP_DOWNLOAD_TIMEOUT

Covers every attempt and backoff delay; http_timeout separately catches stalled connections. When the server supports byte ranges and sends a strong ETag or Last-Modified value, mise keeps a partial download and resumes it on the next attempt, even in a later run; otherwise the download starts over. Changing the URL or request headers discards the partial file.

http_retries

Number of retries after a transient HTTP failure.

• Type: integer
• Default: 3
• Environment variable: MISE_HTTP_RETRIES

mise retries only transient errors: HTTP 5xx, 408 (Request Timeout), 429 (Too Many Requests) and network failures such as a refused connection, a timeout or a dropped response body. Other 4xx responses, such as 404, are not retried. Retries back off with jitter, roughly 200ms, 1s, 4s and 15s. Set to 0 to turn retries off.

Commands that prefer offline data, including shims and shell activation, never retry remote lookups: they make one attempt when cached data is not enough, then fail or fall back. Downloading a tool they install, such as the first mise exec, still retries. When a retry succeeds, mise logs a warning with the original error.

http_timeout

Timeout for connecting or waiting between reads during HTTP requests.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "30s"
• Environment variable: MISE_HTTP_TIMEOUT

The read timer restarts whenever data arrives, so a long download is limited by http_download_timeout instead.

idiomatic_version_file_disable_files

Idiomatic version files to ignore for one tool, as tool:filename pairs.

• Type: string[]
• Default: []
• Environment variable: MISE_IDIOMATIC_VERSION_FILE_DISABLE_FILES (comma-separated)

Turns off one file for one tool without disabling that tool's other version files or other tools that read the same file. To keep .nvmrc but stop node from reading devEngines.runtime in package.json:

mise settings add idiomatic_version_file_disable_files node:package.json

idiomatic_version_file_enable_tools

Tools that read idiomatic version files such as .node-version or .ruby-version.

• Type: string[]
• Default: []
• Environment variable: MISE_IDIOMATIC_VERSION_FILE_ENABLE_TOOLS (comma-separated)

Idiomatic version files are off by default. To turn them on for Node.js and Python:

mise settings add idiomatic_version_file_enable_tools node
mise settings add idiomatic_version_file_enable_tools python

See Idiomatic version files.

ignored_config_pathsmiserc

Config files and directories mise does not load.

• Type: path[]
• Default: []
• Environment variable: MISE_IGNORED_CONFIG_PATHS (separated by : (; on Windows))
• Set in: a .miserc.toml file or MISE_IGNORED_CONFIG_PATHS. mise reads it before config files load, so [settings] in mise.toml has no effect. See settings read before config files.

Entries are paths or glob patterns, including **. A path without glob characters also matches everything under it. Relative paths in a .miserc.toml resolve from the directory that holds it, and relative paths in MISE_IGNORED_CONFIG_PATHS from the directory where you run mise.

Commands that act on every tracked config (mise prune, mise ls --prunable and the stale-version check in mise upgrade) honor only the environment variable and the global and system miserc.toml files, so a project's .miserc.toml cannot hide other projects' configs from them.

mise settings and mise settings add refuse this setting, because mise reads it before config files load; put it in a .miserc.toml file or the environment variable instead.

install_layoutexperimental

Name installations by what they are (identity) instead of installs/<tool>/<version> (legacy).

• Type: string
• Default: identity on Windows with experimental = true, otherwise legacy
• Environment variable: MISE_INSTALL_LAYOUT
• Choices:
  • legacy
  • identity

With identity, each installation goes into an installs/<label>-<hash>/ directory named by its identity (backend, version, platform and install-affecting options), and installs/<tool>/<version> stays as a link to it. Shorthands such as age and aqua:FiloSottile/age then share one install, and variants of one version that differ in an install-affecting option can coexist. Existing installs stay where they are and keep working.

It requires experimental = true. On Windows, experimental = true turns it on by itself; set install_layout = "legacy" to keep the legacy layout there. On other platforms, set both:

[settings]
experimental = true
install_layout = "identity"

See Identity install layout for what changes and what does not.

java

java.shorthand_vendor

Vendor used for a Java version without a vendor prefix, such as java@21.

• Type: string
• Default: "temurin"
• Environment variable: MISE_JAVA_SHORTHAND_VENDOR

Versions without a vendor prefix, such as java@21, java@lts or java@latest, install this vendor's builds. The default is temurin (Eclipse Temurin), which keeps publishing quarterly updates for long-term-support releases.

Earlier versions of mise defaulted to openjdk. jdk.java.net publishes OpenJDK builds only until the next feature release, so with that vendor java@21 stays on 21.0.2. To keep the old behavior, set this to openjdk, or request openjdk-21 explicitly. Temurin has no builds of Java 9, 10 or 12 through 15; request those with an openjdk- prefix.

Installed versions are not changed: a version such as 21.0.2 installed from OpenJDK keeps resolving to that OpenJDK build when the current vendor does not publish it. A lockfile entry records the vendor setting that resolved it, so an entry written with openjdk matches only while this setting is openjdk. With another vendor, mise install --locked reports that the tool is not in the lockfile. Plain mise lock locks the installed OpenJDK build again under the new setting; run mise lock --bump java to lock the new vendor's build instead.

[settings]
java.shorthand_vendor = "openjdk"

jobs

How many jobs to run concurrently such as tool installs. Values below 1 are treated as 1.

• Type: integer
• Default: 8
• Environment variable: MISE_JOBS

libc

Libc build to install on Linux when a tool publishes both glibc and musl builds.

• Type: string
• Default: unset
• Environment variable: MISE_LIBC
• Choices:
  • glibc
  • gnu
  • musl

When unset, mise uses musl builds on a detected musl host, and leaves a glibc host unqualified rather than pinned to glibc, so a backend that picks assets by name can still choose a musl build there. Set it to require the glibc build, for example when a package's musl build misbehaves:

[settings]
libc = "glibc"

gnu is accepted as an alias for glibc.

locked

Require tool versions and download URLs to come from the lockfile.

• Type: boolean
• Default: false
• Environment variable: MISE_LOCKED

Resolves tools only from lockfile entries, instead of looking versions and URLs up through the GitHub API or a registry. A tool with no matching entry is an error, both for installs and for lookups such as mise which, even when the tool is already installed. Backends that lock download URLs must have one for the current platform, and recorded dependency graphs must be present and match their digest; backends that do not lock URLs, such as cargo, go, gem and asdf, need only the version. Installs in this mode do not update lockfiles. Same as passing --locked.

Use it in CI to avoid API rate limits and to catch an incomplete lockfile early; create the entries with mise lock. Locked mode reads existing lockfiles even when lockfile is unset, and fails with lockfile = false. It does not make installs offline: downloads, provenance checks and private-repository API downloads can still need network access and authentication. locked_scopes limits which config scopes it applies to. See Strict lockfile mode.

locked_scopesglobal only

Config scopes where invocation-wide locked mode is enforced.

• Type: string[]
• Default: ["global", "project", "system"]
• Environment variable: MISE_LOCKED_SCOPES (comma-separated)
• Set in: global or system config, or MISE_LOCKED_SCOPES. Ignored, with a warning, in project config. See global-only settings.
• Choices:
  • project
  • global
  • system

Limits invocation-wide locked mode (--locked, MISE_LOCKED=1 or locked = true) to tools from these config scopes; global is your user config. For example, a distribution that declares rolling tools in system config can exclude them while keeping strict locking for project and user tools:

[settings]
locked_scopes = ["project", "global"]

Tools given as command arguments or through environment variables have no config scope, so invocation-wide locked mode always applies to them. A config root's [tool_config] locked = true applies even when its scope is not listed. Excluding a scope relaxes locked mode there; mise still reads existing lockfiles. Project config cannot set this, so a repository cannot weaken your locked-mode policy.

locked_verify_provenance

Re-verify provenance at install time even when the lockfile already records it.

• Type: boolean
• Default: false
• Environment variable: MISE_LOCKED_VERIFY_PROVENANCE

By default, when a lockfile entry has both a checksum and a provenance type, mise install trusts the lockfile and does not verify provenance (SLSA, cosign, minisign or GitHub artifact attestations) again, which saves API calls. With true, mise verifies every time, at the cost of more network requests. paranoid turns it on.

lockfile

Create, read and update mise.lock lockfiles for tool versions.

• Type: boolean
• Default: unset
• Environment variable: MISE_LOCKFILE

A lockfile records the exact version, download URLs and checksums resolved for each tool, so every machine installs the same build even when mise.toml asks for node = "24".

• true in a config file: create, read and update lockfiles for project config.
• unset: read and update lockfiles that exist, but create none; run mise lock to create one. MISE_LOCKFILE=1 behaves the same way.
• false: ignore lockfiles. locked mode fails with this value.

A lockfile normally sits next to its config file and is named mise.lock, or mise.local.lock, mise.<env>.lock or mise.<env>.local.lock for local and environment config; .config/mise/config.toml uses .config/mise/mise.lock, and fragments in conf.d share the lockfile of the directory that holds conf.d. Global lockfiles are created only by mise lock --global. See Lockfile and which lockfile a tool uses.

lockfile_auto_prune

Remove lockfile tools that are absent from the active configuration.

• Type: boolean
• Default: true
• Environment variable: MISE_LOCKFILE_AUTO_PRUNE

By default, a full mise lock removes entries for tools that the active configuration does not declare, which keeps a lockfile in step with one configuration. Set this to false for a lockfile shared by config environments that declare different tools:

[settings]
lockfile_auto_prune = false

It changes only which tools are kept: configured tools still refresh, and their stale versions, option variants and native dependency graphs are still removed. It applies in both lockfile_mode values and to mise lock --global. A filtered command such as mise lock node keeps tools outside its filter anyway.

lockfile_mode

How lockfiles are written: entry by entry, or rebuilt from the current requests.

• Type: string
• Default: "merge"
• Environment variable: MISE_LOCKFILE_MODE
• Choices:
  • merge: update entries as tools are installed
  • generate: rebuild the whole lockfile from the current requests, reusing unchanged entries, and lock other platforms during installs

Neither mode creates lockfiles; set lockfile = true or run mise lock. generate is a trial, and the default may change. See Complete lockfile generation.

lockfile_platforms

Platforms to resolve lockfile URLs and checksums for.

• Type: string[]
• Default: unset
• Environment variable: MISE_LOCKFILE_PLATFORMS (comma-separated)

Applies to mise lock without --platform and to automatic locking during mise install and mise use. The current platform is always added. Listing only the platforms you use keeps lockfiles smaller and installs faster. An explicit mise lock --platform ignores this setting.

[settings]
lockfile_platforms = ["macos-arm64", "linux-x64"]

When unset, mise keeps the platforms already recorded in the lockfile, and automatic locking also adds the current platform. A new lockfile gets linux-x64, linux-x64-musl, linux-arm64, linux-arm64-musl, macos-x64, macos-arm64 and windows-x64, plus the current platform. Write platforms as os-arch or os-arch-qualifier, such as linux-x64-musl.

minimum_release_age

Skip versions published more recently than this duration or date.

• Type: string
• Default: "24h"
• Environment variable: MISE_MINIMUM_RELEASE_AGE

Holds back newly published versions to limit supply-chain risk. Accepts a duration such as 7d, 6mo or 1y, or a cutoff date such as 2024-06-01 or 2024-06-01T12:00:00Z; 0s turns the delay off.

[settings]
minimum_release_age = "7d"

The 24h default applies to aqua, cargo, core, forgejo, gem, github, gitlab, go, npm, packslip, pypi, spm and ubi tools. Tools from asdf, vfox (including vfox plugin backends), conda, dotnet, http, s3 and spinel get no default cutoff. A value you set applies to every backend, except for tools in minimum_release_age_excludes.

The cutoff applies when mise resolves a version request such as node@22 or latest, for backends that report release dates. Exact versions such as node@22.5.0, and versions recorded in mise.lock, are not filtered. The npm: and pypi: backends also pass the cutoff to the package manager for unpinned transitive dependencies. Override it for one tool with the minimum_release_age tool option, or for one command with --minimum-release-age. See Minimum release age.

minimum_release_age_excludes

Tools and backends that the configured and default minimum_release_age do not apply to.

• Type: string[]
• Default: []
• Environment variable: MISE_MINIMUM_RELEASE_AGE_EXCLUDES (comma-separated)

An entry matches a backend wildcard such as npm:*, a registry short name such as trivy, or a full backend ID such as aqua:aquasecurity/trivy:

[settings]
minimum_release_age = "7d"
minimum_release_age_excludes = ["trivy", "npm:*"]

A tool's own minimum_release_age option and --minimum-release-age still apply to excluded tools. Lists from several config files are combined, so a project can add exclusions without repeating global ones; MISE_MINIMUM_RELEASE_AGE_EXCLUDES replaces the combined list.

netrc

Use a netrc file for HTTP Basic authentication.

• Type: boolean
• Default: true
• Environment variable: MISE_NETRC

mise reads credentials from the netrc file and sends them to matching hosts with HTTP Basic authentication, such as a private Artifactory or Nexus server. The file is ~/.netrc on Unix and macOS. On Windows, mise looks for %USERPROFILE%\_netrc, then %USERPROFILE%\.netrc. Use netrc_file for another location.

machine artifactory.example.com
  login myuser
  password mytoken

netrc_file

Path of the netrc file to use instead of ~/.netrc (%USERPROFILE%\_netrc on Windows).

• Type: path
• Default: unset
• Environment variable: MISE_NETRC_FILE

no_env

Do not load environment variables from config files.

• Type: boolean
• Default: unset
• Environment variable: MISE_NO_ENV

Same as the global --no-env flag. See Environment variables.

no_hooks

Do not execute hooks from config files.

• Type: boolean
• Default: unset
• Environment variable: MISE_NO_HOOKS

Same as the global --no-hooks flag. See Hooks.

node

node.apply_patches

Patch files or URLs to apply to the Node.js source before building it.

• Type: string
• Default: unset
• Environment variable: MISE_NODE_APPLY_PATCHES

List one patch file or URL per line. mise applies them to the extracted source before ./configure runs. They apply only to source builds: with node.compile = true, or when no precompiled build exists for the version and mise compiles instead. When mise installs a precompiled build, it warns that the patches were skipped.

node.cflags

Extra CFLAGS for compiling Node.js, for example to replace -O3.

• Type: string
• Default: unset
• Environment variable: MISE_NODE_CFLAGS

When unset, mise uses NODE_CFLAGS from the environment.

node.compile

Compile Node.js from source instead of using a precompiled build.

• Type: boolean
• Default: unset
• Environment variable: MISE_NODE_COMPILE

false uses only precompiled builds and fails when none exists. When unset, all_compile decides; if that is unset too, mise uses a precompiled build when one exists and compiles otherwise. See Building from source.

node.concurrency

Number of parallel jobs (make -j) when compiling Node.js.

• Type: integer
• Default: physical CPU cores, or unset when node.ninja is on
• Environment variable: MISE_NODE_CONCURRENCY

Values below 1 count as 1. With node.ninja, ninja picks the job count when this is unset.

node.configure_opts

Extra arguments for ./configure when compiling Node.js.

• Type: string
• Default: unset
• Environment variable: MISE_NODE_CONFIGURE_OPTS

When unset, mise uses NODE_CONFIGURE_OPTS from the environment.

node.corepack

Run corepack enable after installing a Node.js version, so yarn and pnpm go through Corepack.

• Type: boolean
• Default: false
• Environment variable: MISE_NODE_COREPACK

Applies to Node.js versions that include Corepack. When node.npm_shim is off, mise also runs corepack enable npm. mise installs package managers itself, so Corepack is optional; see Corepack.

node.default_packages_filedeprecated

File listing npm packages to install globally into each new Node.js version.

• Type: path
• Default: "~/.default-npm-packages"
• Environment variable: MISE_NODE_DEFAULT_PACKAGES_FILE
• Deprecated: Default npm package files are deprecated. Use tool-level postinstall hooks for packages that should be installed into every node version, or use the npm: backend for CLI tools.

One package per line, with an optional version:

typescript@latest
@types/node@^24

When this is unset, mise uses NODE_DEFAULT_PACKAGES_FILE, then ~/.default-nodejs-packages or ~/.default-node-packages if one exists, and otherwise ~/.default-npm-packages. See Default packages file.

node.flavor

Linux build flavor of Node.js to download, such as musl or glibc-217.

• Type: string
• Default: unset
• Environment variable: MISE_NODE_FLAVOR

Flavors come from the unofficial builds project, so also set node.mirror_url to https://unofficial-builds.nodejs.org/download/release/. musl is the exception: with the default mirror, mise downloads it from the unofficial builds by itself, and it selects musl automatically on musl hosts. See Unofficial builds.

node.gpg_verify

Check the OpenPGP signature of the SHASUMS256.txt file that node.verify checks downloads against.

• Type: boolean
• Default: true
• Environment variable: MISE_NODE_GPG_VERIFY

mise checks the signature itself, so gpg does not need to be installed. It runs only when node.verify is on, and skips releases that never published a signature (the .sig download returns 404). Set to false to skip the check. The global gpg_verify setting sets the default.

node.make

Command to run instead of make when compiling Node.js, such as gmake.

• Type: string
• Default: unset
• Environment variable: MISE_NODE_MAKE

Used for both the build and make install.

node.make_install_opts

Extra arguments for make install when compiling Node.js.

• Type: string
• Default: unset
• Environment variable: MISE_NODE_MAKE_INSTALL_OPTS

When unset, mise uses NODE_MAKE_INSTALL_OPTS from the environment.

node.make_opts

Extra arguments for make when compiling Node.js.

• Type: string
• Default: unset
• Environment variable: MISE_NODE_MAKE_OPTS

When unset, mise uses NODE_MAKE_OPTS from the environment.

node.mirror_url

Base URL that mise downloads Node.js archives and their SHASUMS256.txt checksums from.

• Type: URL
• Default: "https://nodejs.org/dist/"
• Environment variable: MISE_NODE_MIRROR_URL

When unset, mise uses NODE_BUILD_MIRROR_URL from the environment, then the default. With the default URL, musl builds come from the unofficial builds site instead. See Unofficial builds.

node.ninja

Build Node.js with ninja instead of make when compiling from source.

• Type: boolean
• Default: true when ninja is on PATH
• Environment variable: MISE_NODE_NINJA

With ninja, and node.concurrency unset, ninja chooses how many jobs to run in parallel.

node.nodenv_root

Root directory of nodenv, which mise sync node --nodenv imports Node.js versions from.

• Type: path
• Default: "~/.nodenv"
• Environment variable: NODENV_ROOT

node.npm_shim

Wrap each Node.js version's npm so that npm install -g runs mise reshim afterwards.

• Type: boolean
• Default: true
• Environment variable: MISE_NODE_NPM_SHIM

The wrapper reshims after global installs and uninstalls, so new global commands get shims. It is not installed on Windows. Turn it off to let Corepack or a global npm install -g npm@... manage bin/npm directly. See Global npm packages.

node.nvm_dir

Directory of nvm, which mise sync node --nvm imports Node.js versions from.

• Type: path
• Default: "~/.nvm"
• Environment variable: NVM_DIR

node.verify

Verify downloaded Node.js archives against the SHA-256 checksums in SHASUMS256.txt.

• Type: boolean
• Default: true
• Environment variable: MISE_NODE_VERIFY

When the lockfile has no checksum for an archive, mise downloads SHASUMS256.txt, checks its OpenPGP signature as node.gpg_verify allows, and records the archive's checksum. Setting this to false skips both the checksum file and its signature check. A checksum already in the lockfile is still verified.

not_found_auto_install

Install the tool that provides a command when your shell cannot find that command.

• Type: boolean
• Default: true
• Environment variable: MISE_NOT_FOUND_AUTO_INSTALL

When a command is not found in a shell where mise is activated, or a shim cannot resolve its tool, mise installs the tool that provides the command if a config file for the current directory requests that tool. It finds the tool from the registry's list of each tool's commands, so this also covers a configured tool that has never been installed. A tool configured with a backend identifier such as github:owner/repo or cargo:name has no such list, so mise finds it only once a version of it is installed. Turn this off if the handler interferes with your shell's own command-not-found behavior.

To also install tools that no config requests, enable not_found_auto_install_registry. Has no effect when auto_install is false. See Typing a missing command does not install it.

not_found_auto_install_registry

Install an unconfigured tool when exactly one registry entry provides a command your shell cannot find.

• Type: boolean
• Default: false
• Environment variable: MISE_NOT_FOUND_AUTO_INSTALL_REGISTRY

When not_found_auto_install finds no configured tool for the command, mise looks the command up in the registry. If exactly one enabled tool provides it, mise installs that tool's latest version and adds it to the global config, as mise use --global <tool> does. Ambiguous matches are skipped, and tools in auto_install_disable_tools are never installed this way.

not_found_system_fallback

Let a shim run a same-named executable from elsewhere on PATH when mise cannot resolve the tool.

• Type: boolean
• Default: true
• Environment variable: MISE_NOT_FOUND_SYSTEM_FALLBACK

This can make a configured but uninstalled tool silently run an unrelated system binary, which is common for commands the OS also ships, such as python3. Set both this and not_found_auto_install to false to make such a shim fail instead.

npm

npm.package_manager

Package manager that installs npm: tools.

• Type: string
• Default: "auto"
• Environment variable: MISE_NPM_PACKAGE_MANAGER
• Choices:
  • auto: the embedded aube, or npm when npm.shell_out is on
  • npm: npm install -g
  • aube: the embedded aube, even when npm.shell_out is on
  • aube_cli: a standalone aube executable
  • bun: bun
  • pnpm: pnpm

Every value except auto and aube needs that executable on PATH. Options such as pnpm_args apply only to the package manager they name. See Choosing an installer.

npm.shell_out

Use the npm CLI instead of mise's built-in client for npm: version metadata and default installs.

• Type: boolean
• Default: false
• Environment variable: MISE_NPM_SHELL_OUT

With this on, mise runs npm view for version metadata, and the default auto npm.package_manager installs with npm install -g instead of the embedded aube. An explicit package manager, including aube, is used as chosen. npm must be installed.

Use it for npm behavior the built-in client does not replicate, or to debug a registry problem with npm itself. See Private registries for the npm configuration the built-in client reads.

oci

oci.default_fromexperimental

Base image for mise oci builds when neither [oci].from nor --from sets one.

• Type: string
• Default: "debian:bookworm-slim"
• Environment variable: MISE_OCI_DEFAULT_FROM

Choose a base whose libc and shared libraries suit the tools you package. Most prebuilt tool binaries need glibc, which the default image and ubuntu:24.04 provide. An Alpine or other musl base needs musl or static builds; changing the base does not rebuild installed tools for another libc. scratch builds without a base image. See Base images.

oci.default_mount_pointexperimental

Directory inside mise oci images that holds tool installs, unless [oci].mount_point sets one.

• Type: string
• Default: "/mise"
• Environment variable: MISE_OCI_DEFAULT_MOUNT_POINT

It must be an absolute path. The image sets MISE_DATA_DIR to it, and tools install under its installs directory, with copied vfox plugins under plugins. The --mount-point flag overrides it for one command.

oci.insecure_registries

Registries, as host or host:port, that mise contacts over plain HTTP instead of HTTPS.

• Type: string[]
• Default: unset
• Environment variable: MISE_OCI_INSECURE_REGISTRIES (comma-separated)

Applies to mise oci commands and to oci:: references in include and in task includes, like Docker's insecure-registries daemon option. Loopback registries such as localhost:5000 always use plain HTTP and need no entry. An entry without a port matches the host on any port.

[settings.oci]
insecure_registries = ["registry.lan:5000", "10.0.0.8:5000"]

See Plain-HTTP registries.

offline

Block every HTTP request, so mise uses only installed tools and cached data.

• Type: boolean
• Default: false
• Environment variable: MISE_OFFLINE

Commands that need the network, such as installing a new tool version, fail. Use it on air-gapped machines or when the network is unreliable. Offline mode also turns on prefer_offline, the softer mode that shims and shell activation use by themselves.

os

Operating system of the precompiled binaries mise downloads.

• Type: string
• Default: host OS
• Environment variable: MISE_OS

darwin is accepted for macos. Other values, such as linux or windows, are used as written.

otel

otel.enabledexperimental

Export OpenTelemetry traces of mise run.

• Type: boolean
• Default: false
• Environment variable: MISE_OTEL_ENABLED

mise exports traces only when a traces endpoint is also set, with OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, and reads other options, such as OTEL_EXPORTER_OTLP_HEADERS and OTEL_SERVICE_NAME, from the standard OpenTelemetry variables. Because export needs this setting too, an endpoint set for another tool does not make mise send data. Export does not need experimental = true, and offline mode turns it off.

Task output is exported separately, with otel.logs. See OpenTelemetry.

otel.logsexperimental

Export each line of task stdout and stderr as an OpenTelemetry log record.

• Type: boolean
• Default: false
• Environment variable: MISE_OTEL_LOGS

mise exports logs only when a logs endpoint is also set, with OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT. Each record is linked to its task's span, which otel.enabled exports.

This is separate from otel.enabled because it sends task output, including any secret a task prints, to the collector. With log export on, interleave tasks get a pipe instead of the terminal, which can change programs that check for a TTY, such as their colors, progress bars and prompts. See Logs.

override_config_filenamesmiserc

Project config filenames that mise looks for instead of mise.toml, .mise.toml and the other standard names.

• Type: string[]
• Default: []
• Environment variable: MISE_OVERRIDE_CONFIG_FILENAMES (colon-separated)
• Set in: a .miserc.toml file or MISE_OVERRIDE_CONFIG_FILENAMES. mise reads it before config files load, so [settings] in mise.toml has no effect. See settings read before config files.

In each directory, mise loads only files with these names, and environment-specific files such as mise.development.toml still load. The first name is also the name new config files get. For example, to load mise.toml but not mise.local.toml or .mise.toml:

export MISE_OVERRIDE_CONFIG_FILENAMES=mise.toml

override_tool_versions_filenamesmiserc

Filenames that mise reads as .tool-versions files instead of .tool-versions.

• Type: string[]
• Default: []
• Environment variable: MISE_OVERRIDE_TOOL_VERSIONS_FILENAMES (colon-separated)
• Set in: a .miserc.toml file or MISE_OVERRIDE_TOOL_VERSIONS_FILENAMES. mise reads it before config files load, so [settings] in mise.toml has no effect. See settings read before config files.

Set it to none to stop reading .tool-versions files:

export MISE_OVERRIDE_TOOL_VERSIONS_FILENAMES=none

packslip

packslip.exec

Let packslip tools run their own executable at install time to generate resources, such as an agent skill.

• Type: boolean
• Default: false
• Environment variable: MISE_PACKSLIP_EXEC

Some releases offer a resource only as a command, for example one that prints a skill's SKILL.md. With this on, mise runs the newly installed executable during installation to generate it. Resources published as files do not need this setting.

Shell completions are separate: mise may run a declared completion command when the shell asks for completions, or for mise completion --tool, whatever this is set to. See When mise runs a publisher's command.

packslip.stampers

Hosts that must approve a packslip release before mise lists or installs it, each as host=PIN.

• Type: string[]
• Default: unset
• Environment variable: MISE_PACKSLIP_STAMPERS (comma-separated)

A stamper is a registry, mirror or review service that publishes a signed list of the releases it approves. When this is set, a version needs an approval from at least one of these hosts. PIN is the minisign public key the host signs with, the path of its .pub file, or, for a host that signs keylessly from GitHub, an identity prefix:

[settings.packslip]
stampers = [
  "stamps.example.com=/path/to/stamper.pub",
  "reviews.example.com=https://github.com/example/reviews/",
]

Replace the example hosts and key path with a service and pin you trust. A stamp never replaces the vendor's signature, a vendor withdrawal still excludes the version, and a tool with the trust = "vendor" option needs no stamp. See Stamps.

paranoidglobal only

Require explicit, content-bound trust for project config, and re-verify provenance on every install.

• Type: boolean
• Default: false
• Environment variable: MISE_PARANOID
• Set in: global or system config, or MISE_PARANOID. Ignored, with a warning, in project config. See global-only settings.

Every config file outside global and system config needs your approval, which is tied to the file's contents, so any edit needs approval again. .miserc.toml files and configs under trusted_config_paths still load without it. Automatic trust, CI trust and --yes for the trust prompt are turned off, and locked_verify_provenance is turned on. See Paranoid mode.

pin

Make mise use write the resolved version, such as 24.14.0 for node@24, instead of the requested one.

• Type: boolean
• Default: false
• Environment variable: MISE_PIN

Same as passing --pin every time; --fuzzy writes the requested version for one command. To record exact versions without changing mise.toml, use a lockfile.

prefer_offline

Use cached version lists instead of fetching new ones, and go to the network only when nothing is cached.

• Type: boolean
• Default: false
• Environment variable: MISE_PREFER_OFFLINE

Unlike offline, network requests stay possible: when nothing cached answers a request, mise fetches once, with a short timeout and no retries. The versions host is skipped. mise turns this on by itself for shims and for mise activate, mise hook-env, mise env, mise exec, mise direnv, mise ls, mise current, mise where and mise which.

prereleases

Include prereleases in mise ls-remote, latest and prefix matching for every tool.

• Type: boolean
• Default: false
• Environment variable: MISE_PRERELEASES

Same as setting the prerelease = true tool option on every tool. Every backend supports that option except the core java plugin, which selects early-access builds with release_type = "ea" instead. mise ls-remote --prerelease does this for one command.

Without it, mise skips prereleases when it resolves latest or a prefix such as node@24. A version counts as a prerelease when its source flags it, as GitHub and Forgejo releases, npm and .NET do, or when it looks like one, such as 1.0.0-rc1 or 2.0.0-beta.2. mise ls-remote leaves out flagged versions; backends whose source has no flag, such as cargo, gem, go, http, s3, spm, vfox and asdf, flag versions that look like prereleases. Other sources, such as aqua's github_tag version source, list every tag there. Draft releases are always excluded.

provenance_api_failures_fatal

Fail an install when a provenance API, such as GitHub's attestation API, cannot be reached or queried.

• Type: boolean
• Default: true
• Environment variable: MISE_PROVENANCE_API_FAILURES_FATAL

Applies to GitHub artifact attestation lookups for aqua and github backend tools, and to SLSA provenance lookups for github backend tools. Set to false to warn and install without that check, for example on a build network that cannot reach the GitHub API. Checksum failures, provenance that fails verification, and provenance that the lockfile already requires for the tool still fail the install.

prune

prune.exclude

Tools that mise prune never removes, such as node or aqua:BurntSushi/ripgrep.

• Type: string[]
• Default: []
• Environment variable: MISE_PRUNE_EXCLUDE (comma-separated)

mise prune, mise ls --prunable and the automatic removal after mise upgrade keep every version of these tools, even when no tracked config uses them and even when the tool is named on the command line. Name tools as elsewhere in mise: node, core:node and aqua:BurntSushi/ripgrep all work, and a short name matches the same tool as its full name. mise uninstall is unaffected.

Use it for a tool that something outside mise reaches through its install path, or whose old versions you keep on purpose:

[settings]
prune.exclude = ["node", "aqua:BurntSushi/ripgrep"]

pypi

pypi.registry_url

Package index URL that pypi: tools list versions from, with {} in place of the package name.

• Type: string
• Default: "https://pypi.org/pypi/{}/json"
• Environment variable: MISE_PYPI_REGISTRY_URL

Use a JSON API URL such as the default, or a simple index such as https://pypi.org/simple/{}/. A simple index is asked for its PEP 691 JSON form and falls back to PEP 503 HTML. minimum_release_age works when the index supplies PEP 700 upload-time; HTML responses have no timestamps. The URL must start with http:// or https:// and contain {}. mise also derives the index's simple URL from it and passes that to installs, as UV_INDEX for uv or PIP_INDEX_URL for pipx. A tool's registry_url option overrides it for that tool's version list and dependency locking. pipx.registry_url is an older name for this setting. See Private indexes.

pypi.uvx

Install pypi: tools with uv when uv is available, and with pipx otherwise.

• Type: boolean
• Default: true
• Environment variable: MISE_PYPI_UVX

Set to false to install every pypi: tool with pipx. The uv-only tool options with, expose and dependency_prereleases, and dependency-graph locking, are then unavailable. One tool can opt out with the tool option uvx = false, but uvx = true cannot turn uv back on while this is false. pipx.uvx is an older name for this setting. See Using pipx instead of uv.

python

python.compile

Compile Python from source with python-build instead of using a precompiled build.

• Type: boolean
• Default: unset
• Environment variable: MISE_PYTHON_COMPILE

false uses only precompiled builds: installs fail when none exists, and mise ls-remote lists only precompiled CPython builds and PyPy releases. When unset, all_compile decides; if that is unset too, mise uses a precompiled build when one exists and compiles otherwise. Has no effect on Windows, which always uses precompiled builds. See How mise installs Python.

python.default_packages_filedeprecated

Requirements file that mise installs with pip into each new Python version.

• Type: path
• Default: "~/.default-python-packages"
• Environment variable: MISE_PYTHON_DEFAULT_PACKAGES_FILE
• Deprecated: Default python package files are deprecated. Use tool-level postinstall hooks for packages that should be installed into every python version, or use the pypi: backend for CLI tools.

mise runs pip install --upgrade -r with this file. See Default packages file.

python.github_attestations

Verify GitHub artifact attestations of precompiled Python builds from python-build-standalone.

• Type: boolean
• Default: value of github_attestations
• Environment variable: MISE_PYTHON_GITHUB_ATTESTATIONS

python.patch_url

URL of a patch that python-build applies to every Python version it compiles.

• Type: URL
• Default: unset
• Environment variable: MISE_PYTHON_PATCH_URL

Precompiled builds are not patched. To patch each version separately, use python.patches_directory.

python.patches_directory

Directory of per-version patches for the Python versions that python-build compiles.

• Type: path
• Default: unset
• Environment variable: MISE_PYTHON_PATCHES_DIRECTORY

When compiling Python, mise passes <version>.patch from this directory to python-build, for example 3.14.2.patch. If that file does not exist, mise warns and builds without a patch.

python.precompiled_arch

Architecture of the python-build-standalone build that mise downloads, such as x86_64_v3 or aarch64.

• Type: string
• Default: host architecture: x86_64 or aarch64
• Environment variable: MISE_PYTHON_PRECOMPILED_ARCH

On x86-64 Linux, mise picks the build that matches the CPU features mise itself was compiled for, which for official mise releases is the baseline x86_64 build. Set x86_64_v3 to use the faster build on a CPU with AVX2, or x86_64_v2 or x86_64_v4 for other CPU levels. Give only the architecture; set the OS with python.precompiled_os.

python.precompiled_flavor

Build flavor of python-build-standalone to download, such as install_only or freethreaded-install_only_stripped.

• Type: string
• Default: "install_only_stripped"
• Environment variable: MISE_PYTHON_PRECOMPILED_FLAVOR

Flavors are the last part of the asset names in the python-build-standalone releases. When unset, mise prefers install_only_stripped, then install_only, and never picks a free-threaded build. Only flavors of .tar.gz assets match, such as install_only and freethreaded-install_only_stripped; the -full flavors, published as .tar.zst, do not. See Free-threaded Python.

python.precompiled_os

OS part of the python-build-standalone build name that mise downloads, such as unknown-linux-musl.

• Type: string
• Default: host OS: apple-darwin, pc-windows-msvc, unknown-linux-gnu or unknown-linux-musl
• Environment variable: MISE_PYTHON_PRECOMPILED_OS

Set it, with python.precompiled_arch if needed, to download a build for a platform other than the one mise detects, such as unknown-linux-musl on a glibc host.

python.pyenv_repo

Git repository that mise clones pyenv from to get python-build.

• Type: string
• Default: "https://github.com/pyenv/pyenv.git"
• Environment variable: MISE_PYENV_REPO

python.uv_venv_auto

Activate, and optionally create, the virtualenv of the uv project around the current directory.

• Type: boolean | string
• Default: false
• Environment variable: MISE_PYTHON_UV_VENV_AUTO
• Choices:
  • false: off
  • source: activate an existing virtualenv
  • create|source: create the virtualenv with uv when it is missing, then activate it
  • true: deprecated; like create|source, and also exports UV_PYTHON set to the Python version

mise finds the project by walking up to the nearest uv.lock; without one, this does nothing. The environment is .venv next to uv.lock, or the path in UV_PROJECT_ENVIRONMENT. See uv projects.

true warns since mise 2026.7.0 and is removed in mise 2027.7.0. Use "create|source" or "source" instead.

python.uv_venv_create_args

Arguments for uv venv when mise creates a virtualenv with uv.

• Type: string[]
• Default: unset
• Environment variable: MISE_PYTHON_UV_VENV_CREATE_ARGS (colon-separated)

Used by _.python.venv when it sets no uv_create_args, and by python.uv_venv_auto when it creates a virtualenv.

python.venv_create_args

Arguments for python -m venv when _.python.venv creates a virtualenv without uv.

• Type: string[]
• Default: unset
• Environment variable: MISE_PYTHON_VENV_CREATE_ARGS (colon-separated)

A _.python.venv directive's own python_create_args takes precedence.

python.venv_stdlib

Create _.python.venv virtualenvs with python -m venv even when uv is installed.

• Type: boolean
• Default: false
• Environment variable: MISE_VENV_STDLIB

python.uv_venv_auto always uses uv.

quiet

Hide mise's own non-error messages, such as progress and task headers; same as --quiet.

• Type: boolean
• Default: false
• Environment variable: MISE_QUIET

Sets the log level to error. Output from the commands mise runs, such as tasks, still appears; silent hides that too. verbose takes precedence over this setting.

raw

Connect tasks and install commands directly to the terminal's stdin, stdout and stderr.

• Type: boolean
• Default: false
• Environment variable: MISE_RAW

Use it when a task or plugin script needs to prompt for input. mise does not read the output, so it cannot label or redact it. Only one such command runs at a time, so tasks run one after another whatever jobs is set to. Same as --raw.

registry_cache_ttl

How long a downloaded mise registry stays fresh when registry_floating is on.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "1h"
• Environment variable: MISE_REGISTRY_CACHE_TTL

Set to 0s to download it again on every command that may use the network.

registry_floating

Use the latest released mise registry and the current aqua registry, not only the copies built into mise.

• Type: boolean
• Default: false
• Environment variable: MISE_REGISTRY_FLOATING

The built-in copies remain the fallback when a download fails. Each mise release is tested with its built-in registries, so this is off by default; turn it on when your mise package lags behind registry changes, for example on a distribution that updates mise slowly.

mise downloads the mise registry only for commands that may use the network, and keeps it for registry_cache_ttl. The aqua registry follows aqua.registry_cache_ttl.

ruby

ruby.apply_patches

Patch files or URLs to apply to the Ruby source before compiling it, one per line.

• Type: string
• Default: unset
• Environment variable: MISE_RUBY_APPLY_PATCHES

[settings.ruby]
apply_patches = '''
https://example.com/fix.patch
/opt/patches/ruby-yjit.patch
'''

mise applies them through ruby-build, or ruby-install when ruby.ruby_install is on. Precompiled builds are not patched.

ruby.compile

Compile Ruby from source instead of using a precompiled build.

• Type: boolean
• Default: unset
• Environment variable: MISE_RUBY_COMPILE

false uses only precompiled builds: installs fail when none exists, and mise ls-remote and prefixes consider only versions that have one. When unset, all_compile decides; if that is unset too, mise uses a precompiled build when one exists and compiles otherwise. Has no effect on Windows, where mise installs RubyInstaller2 builds. See Precompiled binaries.

ruby.default_packages_filedeprecated

File listing gems to install into each new Ruby version.

• Type: string
• Default: "~/.default-gems"
• Environment variable: MISE_RUBY_DEFAULT_PACKAGES_FILE
• Deprecated: Default ruby gem files are deprecated. Use tool-level postinstall hooks for gems that should be installed into every ruby version, or use the gem: backend for CLI tools.

Each line names a gem, optionally followed by a version constraint or --pre. See Default gems file.

ruby.github_attestations

Verify GitHub artifact attestations of precompiled Ruby builds.

• Type: boolean
• Default: value of github_attestations
• Environment variable: MISE_RUBY_GITHUB_ATTESTATIONS

Applies when ruby.precompiled_url names a GitHub repository, such as the default jdx/ruby. Builds from a URL template are not checked.

ruby.precompiled_arch

Architecture name of precompiled Ruby builds, such as x86_64 or arm64, used with ruby.precompiled_os.

• Type: string
• Default: unset
• Environment variable: MISE_RUBY_PRECOMPILED_ARCH

mise uses it only when ruby.precompiled_os is also set, and then looks for <arch>_<os> builds instead of detecting the platform. Set both to use builds you host with ruby.precompiled_url for a platform jdx/ruby does not publish, such as musl Linux. See Precompiled binaries.

ruby.precompiled_os

OS name of precompiled Ruby builds, such as linux, used with ruby.precompiled_arch.

• Type: string
• Default: unset
• Environment variable: MISE_RUBY_PRECOMPILED_OS

See ruby.precompiled_arch.

ruby.precompiled_url

GitHub repository, as owner/repo, or URL template that mise downloads precompiled Ruby builds from.

• Type: string
• Default: "jdx/ruby"
• Environment variable: MISE_RUBY_PRECOMPILED_URL

A repository must publish releases with assets named like jdx/ruby's. A URL template can use {version}, {platform}, {arch} and {os}. {platform} is macos, arm64_linux or x86_64_linux, or <arch>_<os> from ruby.precompiled_arch and ruby.precompiled_os. {arch} and {os} are the parts of {platform} before and after its last _, such as x86_64 and linux; on macOS they are arm64 and macos. When both of those settings are set, {arch} and {os} are their values as given.

[settings.ruby]
precompiled_url = "https://mirror.example.com/ruby/ruby-{version}.{platform}.tar.gz"

With a URL template, mise cannot list which versions have builds, and it does not verify GitHub artifact attestations.

ruby.ruby_build_cli_opts

Options for ruby-build itself, such as --keep, passed before the version and install directory.

• Type: string
• Default: unset
• Environment variable: MISE_RUBY_BUILD_CLI_OPTS

ruby.ruby_build_opts

Arguments for Ruby's configure, such as --enable-yjit, passed through ruby-build.

• Type: string
• Default: unset
• Environment variable: MISE_RUBY_BUILD_OPTS

mise passes them after ruby-build's -- separator.

ruby.ruby_build_repo

Git repository or ZIP archive URL that mise gets ruby-build from.

• Type: string
• Default: "https://github.com/rbenv/ruby-build.git"
• Environment variable: MISE_RUBY_BUILD_REPO

ruby.ruby_install

Compile Ruby with ruby-install instead of ruby-build.

• Type: boolean
• Default: false
• Environment variable: MISE_RUBY_INSTALL

ruby.ruby_install_opts

Arguments for Ruby's configure, passed through ruby-install.

• Type: string
• Default: unset
• Environment variable: MISE_RUBY_INSTALL_OPTS

mise passes them after ruby-install's -- separator.

ruby.ruby_install_repo

Git repository or ZIP archive URL that mise gets ruby-install from.

• Type: string
• Default: "https://github.com/postmodern/ruby-install.git"
• Environment variable: MISE_RUBY_INSTALL_REPO

ruby.verbose_install

Show ruby-build's full output while compiling Ruby.

• Type: boolean
• Default: unset
• Environment variable: MISE_RUBY_VERBOSE_INSTALL

When unset, it follows verbose.

rust

rust.cargo_home

Directory used as CARGO_HOME for the Rust toolchains that mise manages.

• Type: path
• Default: $CARGO_HOME, otherwise ~/.cargo
• Environment variable: MISE_CARGO_HOME

Set it with rust.rustup_home to keep mise's toolchains apart from another rustup installation. It takes precedence over a CARGO_HOME in your environment, but a CARGO_HOME set in [env] takes precedence over it. See Cargo, rustup and installed binaries.

rust.default_host

Host triple that mise passes to rustup init as --default-host.

• Type: string
• Default: unset
• Environment variable: MISE_RUST_DEFAULT_HOST

rust.rustup_home

Directory used as RUSTUP_HOME for the Rust toolchains that mise manages.

• Type: path
• Default: $RUSTUP_HOME, otherwise ~/.rustup
• Environment variable: MISE_RUSTUP_HOME

Set it with rust.cargo_home to keep mise's toolchains apart from another rustup installation. It takes precedence over a RUSTUP_HOME in your environment, but a RUSTUP_HOME set in [env] takes precedence over it. See Cargo, rustup and installed binaries.

safeglobal only

Load project config without letting it run code or change the environment, for automation that reads untrusted config.

• Type: boolean
• Default: false
• Environment variable: MISE_SAFE
• Set in: global or system config, or MISE_SAFE. Ignored, with a warning, in project config. See global-only settings.

Use it for bots and CI jobs that process config you did not write, such as a bot that runs mise lock --bump on pull request branches. Project config then loads without a trust prompt.

Safe mode refuses template exec() and read_file(), tasks, the postinstall and install_env tool options, asdf plugin scripts, plugin installs, mise secrets and mise daemons, with an error. It skips hooks, as --no-hooks does, and ignores project [env], [shell_alias], [settings], remote includes, [bootstrap] and [dotfiles], so a repository cannot turn off verification, redirect a backend or write files into your home directory. Global and system config still apply. Version resolution and mise.lock updates keep working for backends that query HTTP APIs, such as core tools, aqua:, github:, pypi: and npm:.

See Safe mode for the complete lists and what safe mode does not protect against.

sandbox

sandbox.deny_all

Deny filesystem access, network access and inherited environment variables by default for mise run and mise exec.

• Type: boolean
• Default: false
• Environment variable: MISE_SANDBOX_DENY_ALL

Tasks and the --allow-* flags can still add exceptions. Windows does not enforce filesystem or network rules and filters the environment only partly; mise warns and runs the command anyway. See Sandbox every command.

sandbox.deny_env

Deny environment variable inheritance by default for mise run and mise exec.

• Type: boolean
• Default: false
• Environment variable: MISE_SANDBOX_DENY_ENV

Tasks and the --allow-env flag can still let variables through. On Windows, the command still inherits mise's own environment. See Sandbox every command.

sandbox.deny_net

Deny network access by default for mise run and mise exec.

• Type: boolean
• Default: false
• Environment variable: MISE_SANDBOX_DENY_NET

Tasks and flags cannot make exceptions for particular hosts; see access to particular hosts. Windows does not enforce it; mise warns and runs the command anyway. See Sandbox every command.

sandbox.deny_read

Deny filesystem reads by default for mise run and mise exec.

• Type: boolean
• Default: false
• Environment variable: MISE_SANDBOX_DENY_READ

Tasks and the --allow-read flag can still add exceptions. Windows does not enforce it; mise warns and runs the command anyway. See Sandbox every command.

sandbox.deny_write

Deny filesystem writes by default for mise run and mise exec.

• Type: boolean
• Default: false
• Environment variable: MISE_SANDBOX_DENY_WRITE

Tasks and the --allow-write flag can still add exceptions. Windows does not enforce it; mise warns and runs the command anyway. See Sandbox every command.

self_update

self_update.api_urlglobal only

GitHub API base URL that mise self-update gets mise releases from.

• Type: URL
• Default: "https://api.github.com"
• Environment variable: MISE_SELF_UPDATE_API_URL
• Set in: global or system config, or MISE_SELF_UPDATE_API_URL. Ignored, with a warning, in project config. See global-only settings.

It must use HTTPS. For GitHub Enterprise, include the API path, such as https://github.example.com/api/v3. Use it with self_update.repository to serve updates from a mirror. See Updating mise.

self_update.autoglobal only

Update mise automatically before running eligible commands.

• Type: boolean | string
• Default: false
• Environment variable: MISE_SELF_UPDATE_AUTO
• Set in: global or system config, or MISE_SELF_UPDATE_AUTO. Ignored, with a warning, in project config. See global-only settings.

With true, mise checks for a newer release every self_update.check_duration, before commands that may use the network; a duration such as "1d" sets the interval instead. When one is available, it installs it without updating plugins, then runs the original command again with the new binary. Automatic updates are skipped in CI, in offline and prefer-offline modes, in non-interactive sessions, for shell activation commands, and for installations whose packager disabled self-update.

[settings]
self_update.auto = true

See Updating mise.

self_update.check_durationglobal only

How often automatic updates check for a new mise release when self_update.auto = true.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "7d"
• Environment variable: MISE_SELF_UPDATE_CHECK_DURATION
• Set in: global or system config, or MISE_SELF_UPDATE_CHECK_DURATION. Ignored, with a warning, in project config. See global-only settings.

self_update.minimum_release_age

Skip mise releases published more recently than this, for mise self-update and automatic updates.

• Type: string
• Default: value of minimum_release_age, else 24h
• Environment variable: MISE_SELF_UPDATE_MINIMUM_RELEASE_AGE

Takes precedence over minimum_release_age for mise self-update, automatic updates and update notifications, and accepts the same durations and cutoff dates. 0s turns the delay off. A version named on the command line, such as mise self-update 2026.10.4, skips the delay; --force does not. mise self-update --minimum-release-age overrides this setting.

[settings]
minimum_release_age = "7d"
self_update.minimum_release_age = "24h"

The install script reads MISE_SELF_UPDATE_MINIMUM_RELEASE_AGE instead of this setting; see Installer options.

self_update.repositoryglobal only

GitHub repository, as owner/repo, that mise gets its own releases from.

• Type: string
• Default: "jdx/mise"
• Environment variable: MISE_SELF_UPDATE_REPOSITORY
• Set in: global or system config, or MISE_SELF_UPDATE_REPOSITORY. Ignored, with a warning, in project config. See global-only settings.

Used by mise self-update, automatic updates and update notifications. Point it at a private mirror that holds only the releases your organization approves; the mirror must keep the official archive names and embedded signatures. mise authenticates with its usual GitHub token sources. See Updating mise.

shared_install_dirs

Extra read-only directories that mise searches for installed tool versions.

• Type: path[]
• Default: unset
• Environment variable: MISE_SHARED_INSTALL_DIRS (separated by : (; on Windows))

mise searches these after its own installs directory and never installs into them on its own; mise install --shared <DIR> installs into one. Use them on shared machines, such as Docker images or bastion hosts, where a base set of tools is preinstalled and users add their own. The system installs directory, system_installs_dir, is always searched when it exists and does not need to be listed. See Other shared directories.

shims

shims.exclude

Command names that mise never creates shims for, so they resolve to whatever else is on PATH.

• Type: string[]
• Default: []
• Environment variable: MISE_SHIMS_EXCLUDE (comma-separated)

mise still installs and manages the tool, and the next mise reshim removes existing shims with these names. Version-qualified shims such as python3.12 are still created:

[settings.shims]
exclude = ["python", "python3", "pip", "pip3"]

Lazy-tool and plugin-provided shims skip these names too, but a command wrapper you declare with one of them still works. Only shims are affected: under mise activate without --shims, a tool's whole bin directory is on PATH, so excluded names are still found there. See Exclude commands from shims.

shims_dirglobal only

Directory where mise writes user shims.

• Type: path
• Default: $MISE_DATA_DIR/shims
• Environment variable: MISE_SHIMS_DIR
• Set in: global or system config, or MISE_SHIMS_DIR. Ignored, with a warning, in project config. See global-only settings.

The path must be absolute after ~ expansion. mise reshim can share a directory such as ~/.local/bin, replacing or removing only files it recognizes as mise shims, but mise activate treats the whole directory as a shim directory, so use a dedicated one if you activate mise. Lazy tools declared in user config put their bootstrap shims here. See Rebuild shims with mise reshim.

silent

Hide all output from mise run and mise watch, including what tasks print, except errors; same as --silent.

• Type: boolean
• Default: false
• Environment variable: MISE_SILENT

skills

skills.auto_sync

Link the active tools' agent skills into the project after mise install, mise use, and mise upgrade.

• Type: boolean
• Default: false
• Environment variable: MISE_SKILLS_AUTO_SYNC

mise runs the equivalent of mise skills sync after every install, after mise use changes a version, and after mise upgrade, so the links under skills.dir point at the versions active in the project. Only projects with a mise config get links, and nothing is written outside a project root. mise touches only links it made, and removes stale ones only when skills.prune is on. See Keep project links up to date.

skills.dir

Where mise skills sync links skills: a path under the project root, or under the home directory with --global.

• Type: string
• Default: ".claude/skills"
• Environment variable: MISE_SKILLS_DIR

Set it to the directory the agents you use read, such as .agents/skills. An absolute path is used as written, and --dir overrides it for one run. See Choose a skill directory.

skills.fetch

Fetch the agent skills a tool's packslip declares when installing it.

• Type: boolean
• Default: true
• Environment variable: MISE_SKILLS_FETCH

mise fetches them at install time, so each installed version carries its own copy. Turning this off skips fetching from then on; it does not delete skills already fetched or existing links. See Skills.

skills.prune

Remove links mise made for skills that are no longer active, on every mise skills sync.

• Type: boolean
• Default: false
• Environment variable: MISE_SKILLS_PRUNE

Without it, mise skills sync keeps those links unless you pass --prune. With it, every sync prunes, including the automatic syncs from skills.auto_sync. mise removes only links it made, which point into its installs directory.

slsa

Verify SLSA provenance of downloads whose publisher provides it.

• Type: boolean
• Default: true
• Environment variable: MISE_SLSA

When false, the aqua and github backends skip SLSA checks whatever aqua.slsa and github.slsa say.

sops

sops.age_key

Private age key for decrypting SOPS files, used before any other key source.

• Type: string
• Default: unset
• Environment variable: MISE_SOPS_AGE_KEY

Prefer the MISE_SOPS_AGE_KEY environment variable to writing a private key into a config file. See Where mise finds the age key.

sops.age_key_file

Path of an age key file for decrypting SOPS files, used after sops.age_key and before SOPS_AGE_KEY_FILE.

• Type: path
• Default: unset
• Environment variable: MISE_SOPS_AGE_KEY_FILE

When neither this nor sops.age_key is set, mise tries SOPS_AGE_KEY_FILE, SOPS_AGE_KEY and then ~/.config/mise/age.txt. See Where mise finds the age key.

sops.rops

Decrypt SOPS files with mise's built-in rops library instead of the sops CLI.

• Type: boolean
• Default: true
• Environment variable: MISE_SOPS_ROPS

rops handles age keys. Set to false to run sops decrypt instead, for AWS KMS, GCP KMS, Azure Key Vault, HashiCorp Vault or PGP keys. The CLI is slower and cannot read TOML, so an encrypted .env.toml needs rops. See Choose a decryption method.

sops.strict

Fail when a SOPS file cannot be decrypted, instead of skipping it.

• Type: boolean
• Default: true
• Environment variable: MISE_SOPS_STRICT

Decryption fails when no age key is found, the key cannot decrypt the file, or the sops CLI is missing. Set to false to skip the file and continue.

spm

spm.artifactbundle_only

Install spm: tools only from prebuilt artifact bundles, and fail instead of building from source.

• Type: boolean
• Default: false
• Environment variable: MISE_SPM_ARTIFACTBUNDLE_ONLY

A tool with the artifactbundle = false option, or a version that selects a Git revision, then fails to install. See artifactbundle.

status

status.missing_tools

When to warn that tools requested by config are not installed.

• Type: string
• Default: "if_other_versions_installed"
• Environment variable: MISE_STATUS_MESSAGE_MISSING_TOOLS
• Choices:
  • never: never warn
  • if_other_versions_installed: warn only when another version of the tool is installed
  • always: always warn

mise prints the warning, such as missing: node@24.14.0, from the shell hook of mise activate and from commands such as mise exec and mise env. Tools marked lazy = true are never reported.

status.show_deps_stale

Warn in an activated shell when a [deps] provider with auto = true is out of date.

• Type: boolean
• Default: true
• Environment variable: MISE_STATUS_SHOW_DEPS_STALE

The warning names each stale provider and the reason, such as npm (package-lock.json changed). See Staleness warnings.

status.show_env

When you change directories in an activated shell, list the environment variables that mise adds, changes or removes.

• Type: boolean
• Default: false
• Environment variable: MISE_STATUS_MESSAGE_SHOW_ENV

Names are shown with +, ~ or -, without values. Config files that start or stop applying are listed the same way.

status.show_tools

When you change directories in an activated shell, list the tool versions that become active or inactive.

• Type: boolean
• Default: false
• Environment variable: MISE_STATUS_MESSAGE_SHOW_TOOLS

Versions are shown as +node@24.14.0 or -node@22.21.1.

status.truncate

Cut the lines from status.show_env and status.show_tools to the terminal width.

• Type: boolean
• Default: true
• Environment variable: MISE_STATUS_MESSAGE_TRUNCATE

Setting truncate to false turns this off too.

swift

swift.gpg_verify

Verify the OpenPGP signature of Swift downloads on Linux.

• Type: boolean
• Default: true
• Environment variable: MISE_SWIFT_GPG_VERIFY

mise checks the signature itself, so gpg does not need to be installed. The global gpg_verify setting sets the default.

swift.platform

Linux distribution build of Swift to download, such as ubuntu24.04 or fedora41.

• Type: string
• Default: detected from your Linux distribution
• Environment variable: MISE_SWIFT_PLATFORM

By default, mise detects your distribution and picks the closest build that the Swift release publishes. Set this to force one build, or to install without fetching swift.org's release index. Ignored on macOS and Windows. See Linux distributions.

system_config_fileenv only

One file to use as the system config instead of the config files in /etc/mise.

• Type: path
• Default: unset
• Environment variable: MISE_SYSTEM_CONFIG_FILE
• Set in: MISE_SYSTEM_CONFIG_FILE only. mise reads it before config files load and ignores it in any config file. See environment-only settings.

When unset, mise reads conf.d/*.toml, config.toml, mise.toml and their environment and .local variants in /etc/mise (or MISE_SYSTEM_CONFIG_DIR), and writes such as mise config set --system go to config.toml there. When set, mise reads and writes only this file.

system_deps

What mise does when a plugin's declared system dependencies are missing before it installs a tool.

• Type: string
• Default: "prompt"
• Environment variable: MISE_SYSTEM_DEPS
• Choices:
  • prompt: list what is missing and offer to install it with the first available package manager; without a terminal and without --yes, same as warn
  • auto: install what is missing without asking, using sudo as system_packages.sudo allows
  • warn: list what is missing and the commands to install it, then continue
  • ignore: skip the check

Dependencies that mise can find, however they were installed, are never reinstalled. Missing optional dependencies are reported in one line and never block an install, and the check never fails an install on its own. See System dependencies.

system_installs_dirglobal only

Directory that mise install --system installs into.

• Type: path
• Default: $MISE_SYSTEM_DATA_DIR/installs (/usr/local/share/mise/installs)
• Environment variable: MISE_SYSTEM_INSTALLS_DIR
• Set in: global or system config, or MISE_SYSTEM_INSTALLS_DIR. Ignored, with a warning, in project config. See global-only settings.

Lazy tools declared in the system config install here too. The path must be absolute after ~ expansion. See System installs.

system_packages

system_packages.elevate_with

Command mise uses to get root instead of sudo, such as run0 or doas.

• Type: string
• Default: unset
• Environment variable: MISE_SYSTEM_PACKAGES_ELEVATE_WITH

When unset, mise uses the first of sudo, run0 and doas found on PATH, so hosts without sudo, such as secureblue (run0) or OpenBSD-style setups (doas), work with no configuration. Set it to pin one:

[settings]
system_packages.elevate_with = "run0"

The command is run as <command> <program> <args>.... Without a terminal, mise checks for passwordless sudo with sudo -n true, and runs the command with doas -n or run0 --no-ask-password so it fails instead of prompting; any other command is used only in an interactive terminal. A doas rule that restricts commands must also allow env, which mise uses to pass variables such as DEBIAN_FRONTEND to apt. system_packages.sudo still turns elevation off entirely. See Root privileges and sudo.

system_packages.managers

Package managers that mise may use for [bootstrap.packages] and missing plugin dependencies.

• Type: string[]
• Default: unset
• Environment variable: MISE_SYSTEM_PACKAGES_MANAGERS (comma-separated)

When unset, mise uses every manager in [bootstrap.packages] that is available on the machine. Names match built-in managers and package manager plugins alike:

[settings]
system_packages.managers = ["apt"]

Status lists packages of excluded managers as skipped, and naming an excluded manager with --manager is an error. For per-OS defaults, set it in a platform config file such as mise.linux.toml, which loads only when that environment is active, with -E linux, MISE_ENV or auto_env. See By package manager.

system_packages.ostree

What mise does with dnf: packages on an image-based Fedora host such as Silverblue or Bazzite.

• Type: string
• Default: "error"
• Environment variable: MISE_SYSTEM_PACKAGES_OSTREE
• Choices:
  • error: stop and explain why the packages cannot be installed, and what to do instead
  • layer: layer missing packages with rpm-ostree install; they take effect after a reboot

On a host booted from an ostree image, /usr is read-only and dnf install fails. Packages are layered with rpm-ostree install instead and take effect on the next boot. Layering is discouraged on these systems, so mise does it only when you opt in. See Fedora Atomic hosts.

system_packages.sudo

Let mise run sudo for steps that need root, such as system packages and mise install --system.

• Type: boolean
• Default: true
• Environment variable: MISE_SYSTEM_PACKAGES_SUDO

mise uses sudo only when it is not running as root, and logs each command it runs with sudo. An interactive session can prompt for your password; a noninteractive one needs sudo to work without a password.

In mise bootstrap, this covers every step that needs root: system packages, Linux accounts, system files and directories, system services, the firewall, and Compose projects with sudo = true. Some status checks also use sudo to read root-only state, such as mise bootstrap firewall status. For mise install --system and mise reshim --system, mise prepares files as your user and uses sudo only to move the installation, its links and the system shims into protected system directories. Package manager plugins never use sudo.

Set to false to never run sudo. Steps that need root then fail unless mise already runs as root, and installs into directories you can write still work. See Root privileges and sudo.

system_shims_dirglobal only

Directory where mise reshim --system writes shims for system installs.

• Type: path
• Default: $MISE_SYSTEM_DATA_DIR/shims (/usr/local/share/mise/shims)
• Environment variable: MISE_SYSTEM_SHIMS_DIR
• Set in: global or system config, or MISE_SYSTEM_SHIMS_DIR. Ignored, with a warning, in project config. See global-only settings.

It may be the same directory as shims_dir; mise then manages one combined set of shims. The path must be absolute after ~ expansion. See Shims for system installs.

task

task.auto_infer

Workspace providers whose package scripts mise imports as tasks, such as node.

• Type: string[]
• Default: []
• Environment variable: MISE_TASK_AUTO_INFER (comma-separated)

With ["node"], the scripts of every Node.js workspace package become tasks named like node:@acme/web#build. Requires a monorepo root. An explicit mise task at the same path replaces the imported one. See Node.js package scripts.

task.cache.audit_reportexperimental

File that receives every undeclared path found by the cache.audit task option.

• Type: path
• Default: unset
• Environment variable: MISE_TASK_CACHE_AUDIT_REPORT

mise writes one JSON object per line, with task, kind and path fields, while the console shows at most 20 paths per task. Each mise invocation that audits a task replaces the file with that run's findings; tasks restored from the cache do not run and add nothing. A relative path resolves against the directory mise runs in. See Find undeclared inputs on Linux.

task.cache.remote_modeexperimental

How mise uses the remote task cache server.

• Type: string
• Default: "read-write"
• Environment variable: MISE_TASK_CACHE_REMOTE_MODE
• Choices:
  • read-write: read entries when the local cache misses, and upload new results
  • read-only: read entries without uploading
  • write-only: upload new results without reading entries

mise uploads results only from GitHub Actions and GitLab CI jobs that push to a protected branch. Other runs only read, whatever this is set to, and with write-only they do not use the server at all. mise run --task-cache local-only skips the server for one run. See Who can write.

task.cache.remote_namespaceexperimental

Namespace that keeps this project's entries apart on the remote task cache server.

• Type: string
• Default: unset
• Environment variable: MISE_TASK_CACHE_REMOTE_NAMESPACE

Required when task.cache.remote_url is set. The server also uses it to decide who may read and write. It is an identifier, such as a repository name, not a secret.

task.cache.remote_oidc_audienceexperimentalglobal only

Audience of the GitHub Actions OIDC token that mise requests for the remote task cache.

• Type: string
• Default: unset
• Environment variable: MISE_TASK_CACHE_REMOTE_OIDC_AUDIENCE
• Set in: global or system config, or MISE_TASK_CACHE_REMOTE_OIDC_AUDIENCE. Ignored, with a warning, in project config. See global-only settings.

The workflow needs the id-token: write permission. mise refreshes the token before it expires. task.cache.remote_token and task.cache.remote_token_file take precedence. See GitHub Actions OIDC.

task.cache.remote_tokenexperimentalglobal only

Bearer token that mise sends to the remote task cache server.

• Type: string
• Default: unset
• Environment variable: MISE_TASK_CACHE_REMOTE_TOKEN
• Set in: global or system config, or MISE_TASK_CACHE_REMOTE_TOKEN. Ignored, with a warning, in project config. See global-only settings.

Prefer the MISE_TASK_CACHE_REMOTE_TOKEN environment variable to writing the token into a config file. It takes precedence over task.cache.remote_token_file and OIDC. A request with a credential must use HTTPS, except to a loopback address. See Credentials.

task.cache.remote_token_fileexperimentalglobal only

File that mise reads the remote task cache token from before each request.

• Type: path
• Default: unset
• Environment variable: MISE_TASK_CACHE_REMOTE_TOKEN_FILE
• Set in: global or system config, or MISE_TASK_CACHE_REMOTE_TOKEN_FILE. Ignored, with a warning, in project config. See global-only settings.

Suits rotating credentials such as Kubernetes projected service account tokens. See Credentials.

task.cache.remote_urlexperimental

Base URL of the remote task cache server.

• Type: URL
• Default: unset
• Environment variable: MISE_TASK_CACHE_REMOTE_URL

The server must implement the remote cache protocol; mise appends v1/... to this URL. Remote access also needs task.cache.remote_namespace. When unset, mise uses only the local cache. See Remote task cache.

task.cache_direxperimental

Directory for the task artifact cache.

• Type: path
• Default: $MISE_CACHE_DIR/task-artifacts
• Environment variable: MISE_TASK_CACHE_DIR

mise keeps entries in a versioned subdirectory, such as v2, and includes this directory in mise cache clear and cache pruning. See Storage, retention, and output replay.

task.cache_max_ageexperimental

Remove task artifact cache entries that have not been used for this long.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: unset
• Environment variable: MISE_TASK_CACHE_MAX_AGE

mise enforces it after storing a new entry, and treats an older entry as a miss. Unset or 0s keeps entries regardless of age. It is separate from cache_prune_age.

task.cache_max_sizeexperimental

Maximum total size of the task artifact cache, such as 500MB or 2GiB.

• Type: string
• Default: unset
• Environment variable: MISE_TASK_CACHE_MAX_SIZE

After storing a new entry, mise removes the least recently used entries until the cache fits. Unset or 0 means no limit.

task.disable_paths

Paths that mise does not look for tasks in.

• Type: path[]
• Default: []
• Environment variable: MISE_TASK_DISABLE_PATHS (separated by : (; on Windows))

Relative paths in a config file resolve from that file's config root, and relative paths in the environment variable from the directory mise runs in. See Exclude paths from discovery.

task.disable_spec_from_run_scripts

Build task usage specs only from the usage field, ignoring deprecated arg(), option() and flag() in run scripts.

• Type: boolean
• Default: false
• Environment variable: MISE_TASK_DISABLE_SPEC_FROM_RUN_SCRIPTS

Defining task arguments with arg(), option() and flag() in run scripts is deprecated, and mise 2027.5.0 removes it. Enable this to adopt that behavior now. mise then skips the extra pass that renders run scripts to collect those calls, which also avoids the empty strings the functions return during that pass. Define arguments in the task's usage field instead; see Migrate from Tera argument functions.

task.monorepo_depth

Maximum directory depth for automatic monorepo discovery, which is deprecated.

• Type: integer
• Default: 5
• Environment variable: MISE_TASK_MONOREPO_DEPTH

Only used by automatic monorepo discovery, which mise falls back to when the root config has no [monorepo].config_roots. That fallback is deprecated; list projects in config_roots instead.

1 finds projects/, and 2 finds projects/frontend/. If the walk is slow and every project is at projects/*, set it to 2:

[settings]
task.monorepo_depth = 2

task.monorepo_exclude_dirs

Directory names that automatic monorepo discovery skips.

• Type: string[]
• Default: []
• Environment variable: MISE_TASK_MONOREPO_EXCLUDE_DIRS (comma-separated)

Only used by automatic monorepo discovery, which mise falls back to when the root config has no [monorepo].config_roots. That fallback is deprecated; list projects in config_roots instead.

When empty, mise skips node_modules, target, dist and build. A list you set replaces those defaults, so include any of them you still want skipped, such as ["node_modules", "vendor"].

task.monorepo_respect_gitignore

Skip directories that .gitignore files ignore during automatic monorepo discovery.

• Type: boolean
• Default: true
• Environment variable: MISE_TASK_MONOREPO_RESPECT_GITIGNORE

Only used by automatic monorepo discovery, which mise falls back to when the root config has no [monorepo].config_roots. That fallback is deprecated; list projects in config_roots instead.

task.output

Default output style for mise run.

• Type: string
• Default: interleave when tasks run one at a time, otherwise prefix
• Environment variable: MISE_TASK_OUTPUT
• Choices:
  • prefix: print each line labelled with the task name
  • interleave: print output as it arrives, without labels
  • keep-order: label lines, stream one task live and buffer the others, then print them in definition order as they finish
  • replacing: replace the previous stdout line with each new one, like mise install progress; stderr is printed as is
  • timed: print only stdout lines that stay on screen for more than a second
  • quiet: deprecated; use interleave with task.quiet
  • silent: print nothing from tasks or mise except errors

How much mise prints is a separate choice: task.quiet, --quiet and --silent, or a task's own quiet and silent properties, combine with any style. For example, task.output = "prefix" with task.quiet = true keeps the task-name labels and hides mise's own messages. See Output.

The quiet value is deprecated: it warns from mise 2026.9.3 and is removed in mise 2027.9.3. Use task.output = "interleave" with task.quiet = true instead, or --output interleave --quiet on the command line.

task.quiet

Hide mise's own messages while tasks run, without changing other mise commands.

• Type: boolean
• Default: false
• Environment variable: MISE_TASK_QUIET

Hidden messages include the command line mise prints before a task runs, such as [build] $ cargo build. Task stdout and stderr stay visible, and any task.output style can be combined with this setting.

task.remote_no_cache

Download remote task files and task includes on every run instead of using the cached copy.

• Type: boolean
• Default: unset
• Environment variable: MISE_TASK_REMOTE_NO_CACHE

Applies to tasks whose file is a URL, which mise otherwise keeps until mise cache clear, and to git:: and oci:: task includes. Same as mise run --no-cache. See Remote tasks.

task.run_auto_install

Install missing tools automatically before tasks run.

• Type: boolean
• Default: true
• Environment variable: MISE_TASK_RUN_AUTO_INSTALL

Has no effect when auto_install is false.

task.show_full_cmd

Print each task's full command line instead of truncating it to the terminal width.

• Type: boolean
• Default: false
• Environment variable: MISE_TASK_SHOW_FULL_CMD

Setting truncate to false does this for all output.

task.skip

Names of tasks that mise run skips.

• Type: string[]
• Default: []
• Environment variable: MISE_TASK_SKIP (comma-separated)

task.skip_depends

Run only the tasks named on the command line, skipping their dependencies; same as mise run --skip-deps.

• Type: boolean
• Default: false
• Environment variable: MISE_TASK_SKIP_DEPENDS

task.source_freshness_equal_mtime_is_fresh

Treat a task as up to date when its newest source and its outputs have the same modification time.

• Type: boolean
• Default: false
• Environment variable: MISE_TASK_SOURCE_FRESHNESS_EQUAL_MTIME_IS_FRESH

By default, outputs must be strictly newer than every source. Enable this on filesystems with coarse timestamps, where a build can leave outputs with the same time as its inputs. See Freshness settings.

task.source_freshness_hash_contents

Decide whether a task's sources changed by hashing their contents instead of comparing modification times.

• Type: boolean
• Default: false
• Environment variable: MISE_TASK_SOURCE_FRESHNESS_HASH_CONTENTS

mise compares BLAKE3 hashes of the source contents with those recorded after the last successful run. This is slower, but checkouts and copies that change timestamps do not make a task stale. The first run after you enable it always runs the task. See Freshness settings.

task.timeout

Time limit for a whole mise run invocation, across every task it runs.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: unset
• Environment variable: MISE_TASK_TIMEOUT

A task's own timeout limits each of its commands; whichever limit is reached first stops the task. mise run --timeout overrides this setting.

task.timings

Print each task's elapsed time when it finishes.

• Type: boolean
• Default: true for the prefix, keep-order and timed styles unless output is quiet, otherwise false
• Environment variable: MISE_TASK_TIMINGS

mise run --no-timings hides the elapsed time for one run.

tera_v1deprecated

Render templates with Tera v1 instead of Tera v2.

• Type: boolean
• Default: false
• Environment variable: MISE_TERA_V1
• Deprecated: tera_v1 is a temporary compatibility escape hatch for templates that still need Tera v1 behavior. Update templates to Tera v2 syntax instead.

Use it only for templates that need Tera v1 macros or its lenient handling of undefined variables. In a shared mise.toml, set MISE_TERA_V1 = true under [env] instead: older mise releases treat it as an ordinary environment variable, while they reject an unknown setting. It does not apply to .miserc.toml. See Migrating from Tera v1.

terminal_progress

Show install progress in the terminal window's own progress indicator, with OSC 9;4 escape sequences.

• Type: boolean
• Default: true
• Environment variable: MISE_TERMINAL_PROGRESS

mise sends the sequences only to terminals that support them, such as Ghostty, iTerm2, VS Code's terminal, Windows Terminal and VTE-based terminals such as GNOME Terminal and Ptyxis, and not to Alacritty, WezTerm or kitty.

tool_update

tool_update.check_durationglobal only

How often mise checks for a newer version of a global tool that sets auto_update = true, or of every global tool with tool_update.global_auto = true.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "24h"
• Environment variable: MISE_TOOL_UPDATE_CHECK_DURATION
• Set in: global or system config, or MISE_TOOL_UPDATE_CHECK_DURATION. Ignored, with a warning, in project config. See global-only settings.

A tool can set its own interval instead, such as auto_update = "6h". Intervals under 1h are raised to 1h. See Automatic tool updates.

tool_update.global_autoglobal only

Update every tool in global config automatically, as if each set auto_update to this value.

• Type: boolean | string
• Default: false
• Environment variable: MISE_TOOL_UPDATE_GLOBAL_AUTO
• Set in: global or system config, or MISE_TOOL_UPDATE_GLOBAL_AUTO. Ignored, with a warning, in project config. See global-only settings.

true checks every tool_update.check_duration, and a duration such as "6h" sets the interval instead. A tool's own auto_update takes precedence, so auto_update = false opts one tool out. Tools in project config are never updated, and exact versions such as node = "24.11.1" stay as they are. See Automatic tool updates.

[settings]
tool_update.global_auto = true

truncate

Truncate long terminal output to fit the available width.

• Type: boolean
• Default: true
• Environment variable: MISE_TRUNCATE

Set to false to show complete values in output that fits itself to the terminal, such as table cells and task command lines. Limits on captured command output, HTTP response bodies and history data still apply. AI coding agents always get untruncated output. Commands that truncate also accept --truncate and --no-truncate for one run.

trusted_config_pathsglobal only

Directories whose config files mise trusts without asking.

• Type: path[]
• Default: []
• Environment variable: MISE_TRUSTED_CONFIG_PATHS (separated by : (; on Windows))
• Set in: global or system config, or MISE_TRUSTED_CONFIG_PATHS. Ignored, with a warning, in project config. See global-only settings.

Covers config files at or below these paths, including projects you create there later. ["/"] trusts every config file, which turns trust checks off. They override trust prompts you declined and mise trust --ignore, but ignored_config_paths still stops configs from loading. Paranoid mode still trusts these paths, without tying trust to file contents. See Trust by path.

unix_default_file_shell_argsglobal only

Shell that runs a file task on Unix when the task sets no shell and the file has no shebang or known extension.

• Type: string
• Default: "sh"
• Environment variable: MISE_UNIX_DEFAULT_FILE_SHELL_ARGS
• Set in: global or system config, or MISE_UNIX_DEFAULT_FILE_SHELL_ARGS. Ignored, with a warning, in project config. See global-only settings.

Applies when mise runs the file through a shell instead of executing it: when the file is not executable, or when use_file_shell_for_executable_tasks is on. mise appends the file path as the last argument.

unix_default_inline_shell_argsglobal only

Shell and arguments that run inline scripts on Unix, such as a task's run, hooks and postinstall.

• Type: string
• Default: "sh -o errexit -c"
• Environment variable: MISE_UNIX_DEFAULT_INLINE_SHELL_ARGS
• Set in: global or system config, or MISE_UNIX_DEFAULT_INLINE_SHELL_ARGS. Ignored, with a warning, in project config. See global-only settings.

mise appends the script as the last argument. A task's own shell takes precedence.

upgrade

upgrade.auto_prune

Remove the version that mise upgrade replaced once upgrade.prune_after has passed.

• Type: boolean
• Default: true
• Environment variable: MISE_UPGRADE_AUTO_PRUNE

The old install stays during that grace period, so running processes can keep loading files from it. Set this to false when something outside mise uses that path for good, such as a virtualenv built from a mise-managed interpreter; the old version then stays without a scheduled removal.

Versions still used by another tracked config, a tool stub or a running process are kept, and may be removed up to a day after that use ends. mise upgrade --prune removes the replaced version at once, and --no-prune keeps it without scheduling removal. See upgrade.prune_after.

upgrade.prune_after

Grace period before mise removes a version that mise upgrade replaced.

• Type: duration (for example 30s, 10m, 1h or 7d)
• Default: "24h"
• Environment variable: MISE_UPGRADE_PRUNE_AFTER

The replaced version stays at its original path for this long, and a later mise command removes it. This protects long-running commands that still load files from the old install. Set to 0s to remove scheduled versions on the next mise command. Run mise upgrade --prune or mise prune to remove them in the current one.

url_replacements

URL patterns and replacements that mise's HTTP client applies before sending a request, for mirrors and proxies.

• Type: table
• Default: unset
• Environment variable: MISE_URL_REPLACEMENTS (a JSON object)

A plain key matches anywhere in the URL, and every occurrence is replaced. A key that starts with regex: is a Rust regular expression, and its first match is replaced. Rules apply in order, and the first one that changes the URL wins. MISE_URL_REPLACEMENTS takes the rules as a JSON object.

[settings.url_replacements]
"https://github.com/" = "https://github-mirror.example.com/"

Rerouting api.github.com, or a repository's release and attestation API paths, also stops mise from using mise-versions for that GitHub metadata, so it all comes from the replacement. Rerouting only release downloads does not. See URL replacements.

use_file_shell_for_executable_tasks

Run executable file tasks through a shell instead of executing them directly.

• Type: boolean
• Default: false
• Environment variable: MISE_USE_FILE_SHELL_FOR_EXECUTABLE_TASKS

By default, mise runs a file task that the OS can execute as a program. With this on, mise starts it with a shell, chosen in this order: the task's shell, the file's shebang, its extension (.ps1 runs with pwsh -File), then unix_default_file_shell_args or windows_default_file_shell_args.

use_versions_host

Get version lists, public GitHub release metadata and attestations from mise-versions instead of upstream APIs.

• Type: boolean
• Default: true
• Environment variable: MISE_USE_VERSIONS_HOST

mise-versions is a shared cache that refreshes version lists for registry tools and public GitHub release data on a schedule. Using it avoids GitHub's anonymous rate limit in normal installs, including Docker builds and CI jobs without a GitHub token.

When a command resolves several tools, such as mise outdated or mise upgrade, mise reads one index of every tool's newest versions instead of each tool's version list, and keeps it as long as a version list (fetch_remote_versions_cache). A request the index cannot answer exactly reads that tool's list as before.

When the host does not list a registry tool's versions, mise lists them from the tool's own source. GitHub release data, tags and attestations for public repositories come only from the host: if it fails, mise reports the error rather than spend GitHub's anonymous rate limit. Paranoid mode asks GitHub when the host can't settle an attestation answer. mise asks GitHub directly only for a repository the host does not know, which may be private, and only with GitHub credentials. Private repositories, GitHub Enterprise, custom GitHub API URLs, and installs with this setting off need normal GitHub authentication to stay within GitHub's rate limits.

When url_replacements reroutes api.github.com, or a repository's release or attestation API paths, mise does not use this host for that GitHub metadata; the replacement is the only source, because this host describes only github.com. Rules that reroute only release downloads do not change this, and version lists for registry tools still come from this host.

Every request to the host sends the mise version and invoking shell in the User-Agent. When mise runs in CI, these requests also send an x-mise-ci: true header and end the User-Agent with ci, for example mise/2026.10.10 linux-x64 (2026-10-11) bash ci.

The host's request logs record each request's IP address, path and query, User-Agent, and time. They are kept in private storage for up to 35 days and then deleted automatically. A nightly job turns them into usage counts, such as monthly active users and installs per tool, keyed by a salted hash of the IP address.

Set this to false to stop these requests. mise still downloads Python's list of precompiled builds from this host; see How mise installs Python.

mise ls-remote --no-versions-host skips the host for one command. See A new release is not listed.

use_versions_host_track

Send download statistics to mise-versions after installing a tool.

• Type: boolean
• Default: true
• Environment variable: MISE_USE_VERSIONS_HOST_TRACK

After a successful install of a core or registry tool, mise reports it to mise-versions, which shows tool popularity. Set this to false to opt out. Nothing is sent when use_versions_host is false.

The report is a GET https://mise-versions.jdx.dev/t request whose query parameters carry:

• the tool name, its full backend identifier such as aqua:BurntSushi/ripgrep (with any URL credentials, query string, and fragment removed, and left out when a URL in it cannot be parsed), and the version
• the OS and architecture

The request also sends the mise version and invoking shell, in the User-Agent, and whether it runs in CI.

The host's request logs store the report with your raw IP address, User-Agent, and time in private storage for up to 35 days, then delete it automatically. A nightly job counts installs from these logs, keyed by a salted hash of the IP address.

verbose

Show extra output, such as installation logs, and set the log level to debug; same as --verbose.

• Type: boolean
• Default: false
• Environment variable: MISE_VERBOSE

windows_default_file_shell_argsglobal only

Shell that runs a file task on Windows when the task sets no shell and the file has no shebang or known extension.

• Type: string
• Default: "cmd /c"
• Environment variable: MISE_WINDOWS_DEFAULT_FILE_SHELL_ARGS
• Set in: global or system config, or MISE_WINDOWS_DEFAULT_FILE_SHELL_ARGS. Ignored, with a warning, in project config. See global-only settings.

Applies when mise runs the file through a shell instead of executing it: when Windows cannot run the file by itself, or when use_file_shell_for_executable_tasks is on. mise appends the file path as the last argument.

windows_default_inline_shell_argsglobal only

Shell and arguments that run inline scripts on Windows, such as a task's run, hooks and postinstall.

• Type: string
• Default: "cmd /c"
• Environment variable: MISE_WINDOWS_DEFAULT_INLINE_SHELL_ARGS
• Set in: global or system config, or MISE_WINDOWS_DEFAULT_INLINE_SHELL_ARGS. Ignored, with a warning, in project config. See global-only settings.

mise appends the script as the last argument. A task's own shell takes precedence.

windows_executable_extensions

File extensions, without the dot, that mise treats as executable on Windows.

• Type: string[]
• Default: ["exe", "bat", "cmd", "com", "ps1", "vbs"]
• Environment variable: MISE_WINDOWS_EXECUTABLE_EXTENSIONS (comma-separated)

mise tries them in order when it looks up a command name that has no extension, and a file with one of them counts as a file task. Matching ignores case.

windows_powershell_no_profile

Pass -NoProfile to the PowerShell (pwsh or powershell) that mise starts, so startup profiles are skipped.

• Type: boolean
• Default: true
• Environment variable: MISE_WINDOWS_POWERSHELL_NO_PROFILE

This matches sh -c and zsh -c on Unix, which do not read interactive startup files. A profile that changes PATH, such as one that activates mise or adds the shims directory, can otherwise shadow a task's own tools and cause cannot find binary path errors.

It applies to tasks, hooks and watch_files commands that run through PowerShell, on any OS, and has no effect on cmd, sh, bash or other shells. Set it to false if your tasks rely on variables, functions or aliases from your PowerShell profile.

windows_shim_mode

How mise creates shims on Windows.

• Type: string
• Default: "exe"
• Environment variable: MISE_WINDOWS_SHIM_MODE
• Choices:
  • exe: copy mise-shim.exe as <tool>.exe; works in every shell, with package managers and with where.exe, and needs mise-shim.exe next to mise.exe
  • file: write a .cmd batch file, plus an extensionless script for Git Bash and Cygwin
  • hardlink: create NTFS hard links to mise.exe, which must be on the same volume as the shims
  • symlink: create symbolic links to mise.exe, which needs administrator rights or Developer Mode

Use exe unless a tool needs one of the others. When mise-shim.exe is missing, mise warns and uses file. After mise is upgraded, the next mise reshim rebuilds exe, file and hardlink shims.

write_targets

write_targets.dotfilesglobal only

Global config file where mise dot add creates new [dotfiles] entries.

• Type: path
• Default: unset
• Set in: global or system config. Ignored, with a warning, in project config. See global-only settings.

mise dot edit uses it too when it adds an entry. mise dot track does not: it writes new track entries to the global config.toml, or to conf.d/dotfiles-tracking.toml when another entry already manages the target. Existing entries stay in the file that declares them. The path must be absolute or start with ~/, and name a file that mise loads from the global config directory, such as ~/.config/mise/conf.d/30-dotfiles.toml. See Send global writes to separate files.

write_targets.packagesglobal only

Global config file where --global package commands create new [bootstrap.packages] entries.

• Type: path
• Default: unset
• Set in: global or system config. Ignored, with a warning, in project config. See global-only settings.

Used by mise bootstrap packages use --global and mise bootstrap packages import --global. Existing entries stay in the file that declares them. The path must be absolute or start with ~/, and name a file that mise loads from the global config directory, such as ~/.config/mise/conf.d/20-packages.toml. See Send global writes to separate files.

write_targets.toolsglobal only

Global config file where mise use --global creates new [tools] entries.

• Type: path
• Default: unset
• Set in: global or system config. Ignored, with a warning, in project config. See global-only settings.

Existing entries stay in the file that declares them. The path must be absolute or start with ~/, and name a file that mise loads from the global config directory, such as ~/.config/mise/conf.d/10-tools.toml. See Send global writes to separate files.

yesglobal only

Answer yes to every confirmation prompt, as --yes does.

• Type: boolean
• Default: false
• Environment variable: MISE_YES
• Set in: global or system config, or MISE_YES. Ignored, with a warning, in project config. See global-only settings.

Use it in scripts and CI; mise also turns it on when the CI environment variable is set. It also answers the config trust prompt, which records trust, except in paranoid mode.

zig

zig.use_community_mirrors

Download Zig from the community mirrors that ziglang.org recommends before trying ziglang.org itself.

• Type: boolean
• Default: true
• Environment variable: MISE_ZIG_USE_COMMUNITY_MIRRORS

ziglang.org offers no uptime or speed guarantees and asks automated downloads to use the community mirrors. Every download is verified against the Zig Software Foundation's signing key, so a mirror cannot alter it. When every mirror fails, mise downloads from ziglang.org.

mise refreshes its cached mirror list daily. Without network access to the list, write one mirror URL per line to zig/community-mirrors.txt in the directory that mise cache path prints.