Mise Version Manager

There is no AI here. All content is human-authored and tested for accuracy.

Mise Configuration

How to use the Mise version manager's .mise.toml configuration file to manage language versions, environment variables, tasks, and settings. For either global or project-level configuration.

Mise can be more than a language version manager. It is useful for setting up a development environment on a per-project basis. Though Mise is best known as a version manager for language runtimes such as Node.js, Python, and Ruby, it also supports other software tools such as linters, formatters, and CLI utilities (for example, jq or shellcheck). Mise terminology refers to both language runtimes and development utilities as its "tools."

You can install language versions or other tools from the command line but the full power of Mise as a development environment manager comes from its configuration files. Mise configures three things: tool versions, project environment variables, and automated tasks in a single structured .mise.toml file.

For language-specific configuration examples, see my tutorials on:

Configuring Mise is one step in setting up your Mac for development. See the complete Mac setup checklist.

Before you get started

You'll need a terminal application to install and use the mise version manager. Apple includes the Mac terminal but I prefer Warp Terminal. Warp is an easy-to-use terminal application, with AI assistance to help you learn and remember terminal commands. Download Warp Terminal now; it's FREE and worth a try.

Migrating from the asdf version manager

If you have used asdf, an older version manager for multiple languages, you have seen its .tool-versions file (which only specifies language versions). The mise .mise.toml file goes beyond version pinning to include environment variables and task runners. However, mise can read existing asdf .tool-versions files without conversion, making migration simple. See Mise vs asdf for migration guidance.

Find configuration file locations

First, you need to figure out where to put a .mise.toml configuration file. Usually, it will be in a project root directory but you can create higher-level files that apply settings to all projects. Mise searches for configuration files in multiple locations and applies them in a specific order.

System-wide configuration in /etc/mise/ applies to all users on your Mac. This is rarely used in personal development setups but matters in shared or CI environments.

User-level configuration lives in ~/.config/mise/config.toml. This file contains your default tool versions and environment variables that apply to all projects unless overridden. Commands like mise use --global node@24 modify this file.

Project-level configuration starts with mise.toml in your project's root directory. Mise automatically searches parent directories for mise.toml files, so you can place configuration in a monorepo root or project subdirectory. Project configuration overrides user configuration.

Local overrides use mise.local.toml in your project directory. This file is for personal, machine-specific settings that should not be shared with teammates or committed to version control. Add mise.local.toml to your .gitignore file. Commands like mise use --env local modify this file.

Environment-specific configurations use files like mise.dev.toml, mise.staging.toml, or mise.production.toml. Activate these by setting MISE_ENV=dev before running commands. This approach suits projects with different tool versions per environment.

In precedence order (lowest to highest), configuration applies like this: system configuration gets overridden by user configuration, which gets overridden by project mise.toml, which gets overridden by mise.local.toml, which can be further specialized by environment-specific files.

When you run a mise command that modifies configuration, it writes to the lowest-precedence file in the highest-precedence directory. This means mise use node@24 in a project directory writes to the project's mise.toml, not your global config.

Use mise edit for configuration

The mise edit command is the recommended way to create and modify .mise.toml files. Instead of writing TOML by hand, mise edit launches a terminal-based interactive editor (a TUI) that knows the structure of mise configuration, can search the tool registry, fetch the latest versions, and autocomplete settings.

Using mise edit is better than editing .mise.toml with a terminal text editor. The editor validates your configuration as you build it, so you avoid typos in tool names or invalid settings. It searches the full mise tool registry with fuzzy matching, so you do not need to remember exact tool identifiers. It fetches the latest available versions automatically, so you do not need to look up version numbers. And it auto-detects language runtimes from your project files (reading engines.node from package.json, requires-python from pyproject.toml, or the go directive from go.mod), so existing projects get a pre-populated configuration with no manual work.

Start the editor

Typically, you'll use mise edit in a project directory when you start a new project or add Mise to an existing project.

Run mise edit to open the interactive editor. If a mise.toml file already exists, it loads the current configuration. If not, mise creates a new one, pre-populated with tools it detects from your project files.

$ mise edit

Give a file name if you don't want to use the default mise.toml:

$ mise edit .mise.toml

Preview what would be generated without writing anything:

$ mise edit -n

You can import an existing asdf .tool-versions file:

$ mise edit -t .tool-versions

Navigate the editor interface

The TUI editor displays your configuration as a structured document with collapsible sections. A typical view looks like this:

  mise.toml editor

  [tools]
    node        22
    python      3.13
  + add tool from registry
  + add tool from backend

  [env]
    DATABASE_URL  postgres://localhost/mydb
  + add variable

  [settings]
  + add setting

  s save • q quit

Move the cursor with arrow keys or vim-style bindings (j/k to move up and down, h/l to jump between sections). Press Tab and Shift+Tab to jump between section headers. Press Enter on a section header to collapse or expand it. It's intuitive and easy to navigate.

Add tools from the registry

Remember that "tools" in mise terminology means any managed software, including language runtimes, build tools, and CLI utilities.

Move the cursor to + add tool from registry and press Enter. A fuzzy-search picker appears showing every tool in the mise registry. Start typing to filter. The matcher is forgiving: typing "nod" finds node, and "py" finds python. You can also match against descriptions, so typing "java runtime" surfaces relevant results.

After selecting a tool, the editor fetches its latest version and presents a version selector. Use arrow keys to cycle through different levels of specificity:

  node  ← latest | 22 | 22.14 | 22.14.0 | other... →

Options include latest (always resolves to the newest release), major version alone, major.minor, and the full version string. Select other... to type a custom version or constraint. Press Enter to confirm.

Add tools from a backend

The mise registry covers hundreds of tools, but it does not cover everything. For tools that are not in the registry, mise can install them through a "backend," which is a package manager or installation method that mise delegates to. You tell mise which tool you want and which backend should fetch it, and mise handles installation, version switching, and PATH management just like it would for any registry tool.

Move to + add tool from backend and press Enter. A picker lists the available backends: aqua (Aqua tool registry), asdf (ASDF plugin ecosystem), cargo (Rust crates), go (Go modules), npm (Node packages), pipx (Python CLI tools), spm (Swift packages), ubi (universal binary installer for GitHub releases), and vfox (VersionFox plugins).

After choosing a backend, enter the tool name (for example, ripgrep for cargo, or prettier for npm). The editor fetches the latest version and opens the version selector.

Edit values and manage entries

Press Enter on any value to enter edit mode. A text cursor appears in the value for text editing. For boolean settings (like experimental or quiet), pressing Enter opens a toggle instead. Press r to rename an entry key. Press Backspace on an entry to remove it. Press u to undo the last action.

Save and quit

Press s to save changes to disk without leaving the editor. Press q to quit. If you have unsaved changes, the editor prompts you to save, discard, or go back to editing.

The [tools] section

The [tools] section specifies which tools your project uses and which versions you want. Remember that "tools" in mise terminology means any managed software, including language runtimes, build tools, and CLI utilities. This is the core of mise configuration. While mise edit is the easiest way to build this section, understanding the TOML syntax helps you read and review configuration files and, of course, you can use a text editor to edit the file.

A basic [tools] section lists tool names with their versions.

[tools]
node = "24"
python = "3.14"
go = "1.24"

Tool names must match the official identifiers (lowercase). Common tools include language runtimes (node, python, ruby, go, rust, java) and utilities (jq, shellcheck, terraform), with hundreds of others available in the mise registry. Version specifications can be exact versions, semver ranges, or fuzzy versions that resolve to the latest matching version.

Exact versions pin to a specific release.

[tools]
node = "24.0.0"
python = "3.14.0"

Semver ranges specify a version range using wildcard notation.

[tools]
python = "3.14.*"
node = "24.0.*"

This syntax installs the latest patch version within the specified minor version. Python 3.14.* installs the newest 3.14.x version available.

Fuzzy versions omit patch numbers and resolve to the latest patch release.

[tools]
go = "1.24"
ruby = "3.3"

This differs from the previous syntax because it does not use the asterisk. Fuzzy version 1.24 matches 1.24.0, 1.24.1, and so on, installing the latest available.

The latest keyword installs the most recent stable release.

[tools]
rust = "latest"

Once you define a [tools] section, run mise install to download and install all specified versions.

$ mise install

Mise installs any missing tools. If tools are already installed, this command does nothing. Subsequent mise install runs work in your project directory (or any subdirectory) because mise searches parent directories for configuration.

Add and remove tools from the command line

The mise use command modifies your configuration from the command line without mise edit or a text editor. To add a tool to your global configuration, run this.

$ mise use --global node@24

This command installs Node.js 24 and adds node = "24" to your global (all projects) ~/.config/mise/config.toml file. For project configuration, use the same command without the --global flag.

$ mise use node@24

This writes to your project's mise.toml if one exists, or creates a new file. To remove a tool, open the file with mise edit and delete the entry, or manually edit the configuration file and delete that line, then run mise install again.

Configure the [env] section

The [env] section manages environment variables for your project. These variables are available to any command you run in your project directory. This replaces the need for separate .env files in many cases.

Define environment variables like this, using either mise edit or a text editor:

[env]
NODE_ENV = "development"
DATABASE_URL = "postgres://localhost/mydb"
DEBUG = "true"

Any command you run in the project directory has access to these variables. You can reference them in scripts, your IDE, and applications. This is useful for setting project-specific defaults without cluttering your shell configuration.

Source external .env files

For larger or sensitive configurations, source variables from a separate file.

[[env]]
_.source = "./.env"

This syntax uses [[env]] (double brackets) to create an environment block that sources a .env file. Standard .env format applies, with KEY=value per line. The _.source directive tells mise to load variables from the specified file.

You can have multiple environment blocks that cascade.

[[env]]
_.source = "./.env"
PYTHONPATH = "./src"
NODE_ENV = "development"

[[env]]
_.source = "./.env.local"
API_KEY = "${API_KEY}"

This example loads a shared .env file, then optionally loads machine-specific overrides from .env.local. The ${API_KEY} syntax references values from the sourced files.

Modify your PATH

The _.path directive adds directories to your PATH environment variable.

[env]
_.path = ["./node_modules/.bin", "./bin"]

This adds two directories to your PATH: ./node_modules/.bin (where npm installs executable packages) and your project's ./bin directory. This allows you to call local executables directly without specifying the full path. This is useful if you want a specific executable to be used only within the project, without making it available globally.

Configure the [settings] section

The [settings] section controls mise's behavior and performance. Settings can apply globally or per-project. The mise edit command makes it easy to discover available settings: move to + add setting and a picker lists every valid setting with a short description.

Configure common settings like this.

[settings]
log_level = "info"
shims_on_path = true
plugin_autoupdate = true

log_level controls verbosity. Set it to debug for detailed output when troubleshooting, info for standard operation, or warn to reduce noise. Setting shims_on_path = true includes shims in your PATH (useful for IDEs and CI/CD). Setting plugin_autoupdate = true keeps mise plugins updated automatically.

Other settings control timeouts, trusted configuration paths, and IDE behavior. See the mise settings documentation for a comprehensive list. Most projects work fine with default settings, so customize only when you have specific needs.

Configure tasks in [tasks]

See Mise Tasks for complete task runner documentation, including parallel execution, file-based tasks, dependencies, and watch mode.

The [tasks] section defines project automation commands. Simple tasks can live directly in your .mise.toml file alongside tool versions and environment variables.

[tasks.test]
description = "Run tests"
run = "npm test"

[tasks.build]
depends = ["test"]
run = "npm run build"

For complex tasks, use standalone shell scripts in a .mise/tasks/ directory.

Choose between global and project configuration

Decide whether settings belong in global or project configuration based on scope.

Use global configuration for your system defaults. For example, set your preferred Node.js version, Python version, and common environment variables in ~/.config/mise/config.toml.

$ mise use --global node@24
$ mise use --global [email protected]

Use project configuration for project-specific requirements. Each project's mise.toml specifies exactly which versions that project needs.

[tools]
node = "24"
python = "3.10"

This project uses Node.js 24 and Python 3.10, overriding your global defaults of 24 and 3.14. When you switch to this project directory, mise automatically activates these versions.

Manage personal machine-specific settings

Sometimes you need settings that apply to your machine but should not be committed to the project repository to be shared with team members. This is where mise.local.toml is useful.

Add mise.local.toml to your project's .gitignore file so it is not version-controlled.

$ echo "mise.local.toml" >> .gitignore

Create your local overrides in mise.local.toml.

[tools]
node = "24-nightly"

[env]
MY_LOCAL_API_KEY = "secret-value"

This file overrides your project configuration on your machine only. Other team members use the standard configuration from mise.toml and their own mise.local.toml files.

Support legacy version files

Mise can read version files created by other tools. This means you can use mise while other team members use different version managers without conflicts. Mise calls the other files "idiomatic version files" and supports .nvmrc (nvm for Node.js), .python-version (pyenv for Python), .ruby-version (rbenv for Ruby), .node-version (nodenv for Node.js), and .tool-versions (asdf format).

However, this feature is disabled by default because parsing the "idiomatic" files adds overhead. Enable support for specific tools if you must accommodate team members who don't use mise.

$ mise settings add idiomatic_version_file_enable_tools node python

This command enables automatic parsing of .nvmrc and .python-version files. Settings are stored in your global ~/.config/mise/config.toml and apply everywhere on your machine.

Migrate from .tool-versions

If you are transitioning from asdf, you can import your .tool-versions file directly into the interactive editor:

$ mise edit -t .tool-versions

This loads your existing tool versions into the editor where you can review, adjust versions, add environment variables, and save as a .mise.toml file. After saving, you can safely delete .tool-versions if you want.

A gradual approach works too. Keep .tool-versions during the transition while team members migrate at their own pace. Mise reads .tool-versions automatically, so your existing file continues to work. Eventually, everyone moves to .mise.toml and you can retire the old file.

Choose between shims and PATH mode

Configuration differs slightly depending whether you use PATH mode (for local development) or shims mode (for IDEs and CI/CD).

Use PATH mode for interactive development

For local development, you activated mise in your shell with eval "$(mise activate zsh)". This is PATH mode. Every time your shell prompt appears, mise updates your PATH and environment variables from .mise.toml.

In PATH mode, all environment variables in the [env] section are automatically available to every command.

[env]
NODE_ENV = "development"
DATABASE_URL = "postgres://localhost/db"

When you run any command, these variables are set. This is seamless and natural for interactive terminal work.

Use shims mode for IDEs and CI/CD

IDEs do not display shell prompts, so they cannot use PATH mode activation. Instead, IDEs and CI systems use shims mode. Set shims_on_path = true in your [settings] section.

[settings]
shims_on_path = true

Shims are small wrapper scripts that locate and call mise binaries. When an IDE runs node, it actually runs a shim that loads mise context and then launches Node.js.

Environment variables work differently in shims mode. Variables from the [env] section are only available when the shim is called directly, not to all commands. For IDEs that need environment variables, set them in the IDE's own configuration instead of relying on mise's [env] section.

Use both simultaneously

You can use both modes at the same time with no conflict. Your shell uses PATH mode, while your IDE uses shims mode. Each environment gets what works best for it.

Configure IDE integration

Different IDEs require different setup.

VS Code

Install the official VS Code mise extension. The extension automatically configures your environment and notifies other extensions about mise-managed tools. Once installed, VS Code finds Node.js, Python, and other tools from mise without manual configuration.

JetBrains IDEs (PyCharm, IntelliJ)

JetBrains IDEs have native SDK selection. Go to your IDE's preferences and look for language-specific SDK settings. Select the mise-installed version from the file browser. The path typically looks like ~/.local/share/mise/installs/python/3.14.0 or similar.

If your IDE does not have native mise support, configure the shims path. Add ~/.local/share/mise/shims to your IDE's executable search path. This tells the IDE where to find mise-managed tools.

Zed and other editors

Zed is a lightweight, high-performance editor that works well alongside mise. Most editors and IDEs need the shims directory in their PATH. Set this in IDE settings or preferences, not in mise configuration.

For environment variables needed by your IDE, configure them in the IDE's environment settings rather than relying on mise's [env] section. IDEs launched from the GUI do not read shell configuration, so they cannot access environment variables that way.

Trust configuration files with mise trust

Mise requires explicit trust for configuration files for security. When you use a new project with mise configuration, you see a warning about untrusted files.

Trust a configuration file by running this in the project directory.

$ mise trust

This command marks your current directory's mise.toml as trusted. Mise remembers this decision and will not warn again. You can also trust a specific file.

$ mise trust ~/some_dir/mise.toml

Auto-trust directories

For CI/CD environments or shared development directories, automatically trust entire directories.

[settings]
trusted_config_paths = ["/home/user/projects/work", "/opt/dev"]

Add this to your global ~/.config/mise/config.toml. Any configuration files in these directories are automatically trusted without explicit approval.

This is particularly useful in Docker containers where you want mise to run without user interaction.

$ mise trust -a

This command trusts all configurations. Use it in containerized or automated environments only, never in interactive development.

Set up real-world configurations

Several complete examples show how to combine these concepts.

Configure a Node.js and Python project

A full-stack web application needs both Node.js and Python. Run mise edit in your project directory and add both tools from the registry. The resulting configuration looks like this:

[tools]
node = "24"
python = "3.14"

[env]
NODE_ENV = "development"
DATABASE_URL = "postgres://localhost/myapp"

[settings]
log_level = "info"

This configuration ensures the team uses compatible versions and shares environment setup.

Configure a full-stack project with local overrides

A Rails project with Node.js needs per-environment configuration.

[tools]
ruby = "4.0"
node = "24"

[env]
_.source = "./.env"
RAILS_ENV = "development"

Create mise.local.toml for personal settings that should not be committed.

[env]
API_KEY = "my-secret-key"

The .env file (which IS committed) contains non-sensitive defaults. mise.local.toml (which is git-ignored) contains machine-specific secrets.

Configure a monorepo with multiple environments

A monorepo has services needing different versions.

[tools]
node = "24"
python = "3.14"
go = "1.24"

[settings]
trusted_config_paths = ["."]

Each service subdirectory can override with its own mise.toml.

Services/api/mise.toml:

[tools]
go = "1.19"

This service uses Go 1.19 while the monorepo default is 1.24.

Diagnose configuration issues

The mise doctor command reveals configuration problems.

$ mise doctor

Look for warnings about ignored configuration files. This usually means a file is not trusted or is in an unexpected location. The verbose output shows exactly which files mise loaded and which ones it ignored.

$ mise doctor -vvv

Use verbose mode for detailed debugging. This shows the configuration search path, file processing order, and any errors encountered.

Fix common configuration problems

If configuration is not being loaded, check the file location. Mise searches for .mise.toml or mise.toml in the current directory and parent directories. If your file is named something else or in an unexpected location, mise will not find it.

If tools are not installing, verify your [tools] section has valid syntax and tool names. Tool names must be lowercase and match official tool identifiers. Using mise edit avoids this problem because the editor validates tool names against the registry.

If environment variables are not available, verify you are using PATH mode (not shims mode without proper IDE configuration) or that you have properly sourced external .env files.

If configuration conflicts occur, check the configuration hierarchy. Project configuration overrides global configuration, and mise.local.toml overrides mise.toml. Run mise doctor to see the precedence order on your system.

Follow configuration best practices

Following these practices keeps your configuration maintainable and team-friendly.

Commit mise.toml to version control so all team members use the same tool versions. Use semantic versioning in your tool specifications (fuzzy versions like 3.14 rather than exact versions like 3.14.5). Fuzzy versions ensure security patches are applied automatically while keeping major and minor versions consistent.

Document why specific versions are pinned if there is a non-obvious reason.

# Pinned to 22.x because 24.x broke our build system
node = "22"

Keep sensitive environment variables in mise.local.toml (git-ignored) or source them from .env.local files that are not committed. Never commit API keys or passwords in .mise.toml.

Use mise edit to add new tools and settings. The interactive editor prevents common mistakes like misspelled tool names or invalid setting keys.

Run mise doctor regularly to catch configuration issues before they cause problems.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.