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

> Learn what a .mise.toml file is and how to use it for project specific configurations, tool versions, and environment variables with this complete guide to mise configuration.

- Repository: [jdx/mise](https://github.com/jdx/mise)
- Tags: deep-dive
- Published: 2026-08-09

---

**A [`.mise.toml`](https://github.com/jdx/mise/blob/main/.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`](https://github.com/jdx/mise/blob/main/.mise.toml) or [`.mise/config.toml`](https://github.com/jdx/mise/blob/main/.mise/config.toml)) [docs/dev-tools/comparison-to-asdf.md#L24].

**Configuration lookup order:**

- **Project-specific:** [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml) or [`mise.toml`](https://github.com/jdx/mise/blob/main/mise.toml) in the repository root or subdirectories
- **User-specific:** `~/.config/mise/config.toml` or `~/.mise.toml`
- **System-wide:** [`/etc/mise/config.toml`](https://github.com/jdx/mise/blob/main//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`](https://github.com/jdx/mise/blob/main/.mise.toml) file organizes data into specific TOML tables. The following excerpt from [`test/fixtures/.mise.toml`](https://github.com/jdx/mise/blob/main/test/fixtures/.mise.toml) [test/fixtures/.mise.toml#L1-L20] demonstrates the supported structure:

```toml
[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:**

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

```

**Advanced version specifications:**

```toml
[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`.

```toml
[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.

```toml
[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.

```toml
[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]`.

```toml
[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`](https://github.com/jdx/mise/blob/main/.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`](https://github.com/jdx/mise/blob/main/.mise.toml) with the exact resolved version.

## Security: Separating Secrets with [`.mise.local.toml`](https://github.com/jdx/mise/blob/main/.mise.local.toml)

The [`.mise.toml`](https://github.com/jdx/mise/blob/main/.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`](https://github.com/jdx/mise/blob/main/.mise.toml). Instead, use [`.mise.local.toml`](https://github.com/jdx/mise/blob/main/.mise.local.toml) for environment-specific secrets and add this file to `.gitignore`.

```toml

# .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`](https://github.com/jdx/mise/blob/main/src/config/mod.rs), which reads [`.mise.toml`](https://github.com/jdx/mise/blob/main/.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`](https://github.com/jdx/mise/blob/main/src/cli/config.rs). The comprehensive syntax reference lives in [`docs/configuration.md`](https://github.com/jdx/mise/blob/main/docs/configuration.md), while [`test/fixtures/.mise.toml`](https://github.com/jdx/mise/blob/main/test/fixtures/.mise.toml) provides the canonical example used in the test suite.

## Summary

- **[`.mise.toml`](https://github.com/jdx/mise/blob/main/.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`](https://github.com/jdx/mise/blob/main/.mise.local.toml) rather than the committed [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml).
- **Core parsing** happens in [`src/config/mod.rs`](https://github.com/jdx/mise/blob/main/src/config/mod.rs), with CLI tooling in [`src/cli/config.rs`](https://github.com/jdx/mise/blob/main/src/cli/config.rs).

## Frequently Asked Questions

### What is the difference between [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml) and [`mise.toml`](https://github.com/jdx/mise/blob/main/mise.toml)?

Both filenames are valid. The dot-prefixed [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml) is a hidden file convention suitable for project roots, while [`mise.toml`](https://github.com/jdx/mise/blob/main/mise.toml) is visible. According to the `mise` documentation, dotfiles starting with `mise` (like [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml)) or paths like [`.mise/config.toml`](https://github.com/jdx/mise/blob/main/.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`](https://github.com/jdx/mise/blob/main/.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`](https://github.com/jdx/mise/blob/main/.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`](https://github.com/jdx/mise/blob/main/.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`](https://github.com/jdx/mise/blob/main/.mise.local.toml) rather than [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml). The local variant is intended for machine-specific or sensitive data and should be added to `.gitignore`. The project's [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml) is designed for version-controlled, shareable configuration, while [`.mise.local.toml`](https://github.com/jdx/mise/blob/main/.mise.local.toml) provides uncommitted overrides.