What Is a `.mise.toml` File? Complete Guide to Mise Configuration

A .mise.toml file is a TOML-formatted configuration file used by the mise (formerly rtx) version manager to declare tool versions, environment variables, plugins, and project-specific settings for development environments.

The mise tool—hosted in the jdx/mise repository—uses this file as its primary mechanism for defining reproducible development setups. When placed in a project root or user home directory, it tells mise exactly which runtime versions to install and how to configure the shell environment.

File Location and Configuration Hierarchy

mise supports multiple configuration file locations and merges them hierarchically. According to the source code, paths that start with mise can be dotfiles (e.g., .mise.toml or .mise/config.toml) [docs/dev-tools/comparison-to-asdf.md#L24].

Configuration lookup order:

• Project-specific: .mise.toml or mise.toml in the repository root or subdirectories
• User-specific: ~/.config/mise/config.toml or ~/.mise.toml
• System-wide: /etc/mise/config.toml

mise walks up the directory tree from the current working directory and merges all discovered configurations. This allows global defaults to coexist with project-specific overrides, with deeper files taking precedence.

Core Configuration Sections

A .mise.toml file organizes data into specific TOML tables. The following excerpt from test/fixtures/.mise.toml [test/fixtures/.mise.toml#L1-L20] demonstrates the supported structure:

[env]                     # environment variables

NODE_ENV = 'production'

[tools]                   # tool names and version specifications

terraform = '1.0.0'
node = ['18', 'prefix:20', 'ref:master', 'path:~/.nodes/18']
jq = { prefix = '1.6' }
shellcheck = { version = '0.9.0' }
python = [{ version = '3.10.0', venv = '.venv' }, { version = '3.9.0' }]

[plugins]                 # external plugins (e.g. custom Node plugin)

node = 'https://github.com/jdx/rtx-node'

[settings]                # global `mise` behaviour for this config

verbose = true
disable_tools = ['disabled_tool']
legacy_version_file_disable_tools = ['disabled_tool_from_legacy_file']

[alias.node.versions]    # version aliasing

my_custom_node = '18'

[tools] - Managing Tool Versions

The [tools] table defines which runtimes mise should install and activate. Values can be simple strings or complex objects specifying installation parameters.

Basic version pinning:

[tools]
node = '20'
python = '3.12.0'

Advanced version specifications:

[tools]
node = ['18', 'prefix:20', 'ref:master', 'path:~/.nodes/18']

• 18 – Exact version constraint
• prefix:20 – Latest matching 20.x release
• ref:master – Install from the master branch of the tool's repository
• path:~/.nodes/18 – Use a pre-installed binary at the specified path

[env] - Environment Variables

The [env] table exports variables into the shell environment whenever mise activates the project. These support shell interpolation and modification of existing variables like PATH.

[env]
NODE_ENV = 'development'
PATH = '${PATH}:./bin'
DATABASE_URL = 'postgres://localhost/dev'

[plugins] - External Plugins

Custom tool sources are defined in the [plugins] table, allowing you to override default plugin URLs or add community-supported tools not included in the core distribution.

[plugins]
go = 'https://github.com/jdx/rtx-go'

[settings] - Behavioral Configuration

The [settings] table controls mise behavior for the current configuration scope without affecting global CLI defaults.

[settings]
verbose = true
disable_tools = ['disabled_tool']
legacy_version_file_disable_tools = ['disabled_tool_from_legacy_file']

[alias] - Version Aliasing

Version aliases create human-readable shortcuts for specific tool versions. These are defined under [alias.{tool}.versions].

[alias.node.versions]
lts = '18'
current = '20'

With this configuration, mise use node@lts resolves to Node.js version 18.

Version Resolution and Lockfiles

When a lockfile exists, mise uses version prefixes from .mise.toml to resolve concrete versions. For example, if node = "26" appears in the file, running mise upgrade node --bump installs the newest 26.x release and rewrites the version in .mise.toml with the exact resolved version.

Security: Separating Secrets with .mise.local.toml

The .mise.toml file is intended to be checked into version control. Never store sensitive data such as API keys or database passwords in a project's .mise.toml. Instead, use .mise.local.toml for environment-specific secrets and add this file to .gitignore.

# .mise.local.toml (do not commit this file)

[env]
SECRET_API_KEY = 'sk_live_...'

Implementation in the Mise Codebase

The parsing and merging logic resides in src/config/mod.rs, which reads .mise.toml files and builds the internal configuration model. CLI manipulation commands like mise edit, mise generate config, and mise set are implemented in src/cli/config.rs. The comprehensive syntax reference lives in docs/configuration.md, while test/fixtures/.mise.toml provides the canonical example used in the test suite.

Summary

• .mise.toml is the primary TOML configuration file used by jdx/mise to define development environments, tool versions, and environment variables.
• Configuration merges hierarchically from the current directory up to the user home directory, allowing layered environment setup.
• Key sections include [tools] for version management, [env] for variables, [plugins] for custom sources, [settings] for behavior control, and [alias] for version shortcuts.
• Security separation requires placing sensitive values in .mise.local.toml rather than the committed .mise.toml.
• Core parsing happens in src/config/mod.rs, with CLI tooling in src/cli/config.rs.

Frequently Asked Questions

What is the difference between .mise.toml and mise.toml?

Both filenames are valid. The dot-prefixed .mise.toml is a hidden file convention suitable for project roots, while mise.toml is visible. According to the mise documentation, dotfiles starting with mise (like .mise.toml) or paths like .mise/config.toml are all recognized during configuration discovery [docs/dev-tools/comparison-to-asdf.md#L24]. Functionally, they behave identically.

Can I use multiple .mise.toml files in the same project?

Yes. mise walks up the directory tree and merges all configuration files it finds. You can place a .mise.toml in a subdirectory with additional tool versions or environment variables that layer over the root configuration. Deeper files take precedence over parent directory configurations.

How do I specify multiple versions of the same tool in .mise.toml?

Use a TOML array syntax. For example, node = ['18', '20'] installs both Node.js 18 and 20, making them available simultaneously. You can also mix specification types: node = ['18', 'prefix:20', 'ref:master'] combines exact versions, prefix matching, and git references.

Where should I put sensitive environment variables in mise?

Store secrets in .mise.local.toml rather than .mise.toml. The local variant is intended for machine-specific or sensitive data and should be added to .gitignore. The project's .mise.toml is designed for version-controlled, shareable configuration, while .mise.local.toml provides uncommitted overrides.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}