How to Set a Global Tool Version with mise

To set a global tool version in mise, define the tool and version string in the [tools] table of ~/.config/mise/config.toml or execute mise use -g <tool>@<version> to write the entry automatically.

The jdx/mise repository (formerly rtx) manages tool versions through layered configuration files. Global versions apply across your entire system unless overridden by project-specific settings. According to docs/configuration.md, the global configuration file lives at ~/.config/mise/config.toml and uses TOML syntax to declare default tool versions.

Understanding the Global Configuration File

Mise reads global settings from ~/.config/mise/config.toml before checking local project files. This file contains a [tools] table where each key is a tool name and the value is the desired version.

The configuration parser in src/config/mod.rs loads this file and merges it with project-specific configurations, while src/config/settings.rs defines the data structures that represent the [tools] entries. Because the parser treats version strings as opaque literals, you can specify semantic versions like 20.11.0, aliases like lts, or date-based tags like nightly-2024-01-01.

Methods to Set a Global Tool Version

Manual Configuration (Editing config.toml)

Edit ~/.config/mise/config.toml directly to add tools under the [tools] section:

# ~/.config/mise/config.toml

[tools]
node = "20"
python = "3.12.0"
go = "1.22.4"

Save the file and run mise install to download and activate the specified versions globally.

Using the CLI (mise use -g)

The mise use command, implemented in src/cli/use.rs, provides a -g (or --global) flag that writes entries directly to the global config file:

# Set Node.js version 20 globally

mise use -g node@20

# Set multiple tools at once

mise use -g python@3.12.0 go@1.22.4

# Verify the global configuration

mise list

This approach eliminates manual editing and ensures valid TOML formatting.

How Global Versions Are Resolved

Mise resolves tool versions by merging configuration layers. The global file provides defaults, while project-local mise.toml or .mise.toml files override them. As implemented in src/config/mod.rs, the merge strategy gives precedence to project-specific definitions, allowing you to pin different versions per repository while maintaining system-wide defaults.

# project-specific mise.toml

[tools]
node = "18"   # Overrides the global "20" for this project only

Summary

• Global configuration resides in ~/.config/mise/config.toml under the [tools] table.
• Manual editing requires adding tool = "version" entries to the TOML file.
• CLI convenience: mise use -g <tool>@<version> automatically writes to the global config file via the logic in src/cli/use.rs.
• Precedence: Project-specific configuration files override global versions, with merging handled by src/config/mod.rs.
• Version strings are treated as opaque literals, supporting semantic versions, aliases, and custom tags.

Frequently Asked Questions

Where does mise store global tool versions?

Mise stores global tool versions in ~/.config/mise/config.toml. This file contains a [tools] section where each entry maps a tool name to its version string, which the configuration loader in src/config/mod.rs parses at startup.

Can I override a global version for a specific project?

Yes. Create a mise.toml or .mise.toml file in the project root and define the tool version there. According to the merging logic in src/config/mod.rs, project-local configurations take precedence over the global ~/.config/mise/config.toml.

What file format does the global configuration use?

The global configuration uses TOML format. The [tools] table structure is documented in docs/configuration.md and parsed by the TOML loader in src/config/settings.rs, which preserves exact version strings for backend resolution.

How does the mise use -g command work internally?

The mise use command implements the -g/--global flag in src/cli/use.rs. When invoked, it opens the global config file, modifies the [tools] table to include the specified tool and version, and then triggers the installation process. This ensures the global configuration remains syntactically valid while updating the desired tool version.

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