mise Version Manager

What it is

mise is a polyglot version manager that allows you to install, manage, and switch between multiple versions of various programming languages and tools on your system, often automatically based on project directory.

Installation

Linux

curl -fsSL https://mise.jdx.dev/install.sh | sh

macOS

On macOS, mise can be installed via Homebrew:

brew install mise

Windows

On Windows, mise can be installed via Scoop or Winget:

# Using Scoop
scoop install mise

# Using Winget
winget install mise

Core Concepts

• Shims: mise works by installing executable "shims" in your PATH. When you run a command like node, mise intercepts it, determines the correct version for your current context, and executes that version.
• Local vs. Global Versions: You can set a default version for a tool globally (for your user account) or locally within a specific project directory. Project-local settings override global ones.
• Environment Variables: mise can automatically set environment variables for tools (e.g., JAVA_HOME for Java) when a specific version is active.
• Configuration Files: mise uses configuration files (.mise.toml, ~/.config/mise/config.toml) to define plugins, global versions, and other settings.

Commands / Usage

Installing and Managing Tools

Install a specific version of a tool

mise install node@20.10.0
mise install python@3.11.5
mise install ruby@3.2.2

Installs a specific version of the given tool.

Install the latest stable version of a tool

mise install node@latest
mise install python@latest

Installs the most recent stable release of the tool.

Install the latest version of a tool (including pre-releases)

mise install node@latest-rc

Installs the latest release candidate or pre-release version.

List available versions of a tool

mise list --all node
mise list --all python

Shows all versions of a tool that can be installed.

List installed versions of a tool

mise list node
mise list python

Shows only the versions of a tool that are currently installed.

Uninstall a specific version of a tool

mise uninstall node@20.10.0
mise uninstall python@3.11.5

Removes an installed version of a tool.

Uninstall all versions of a tool

mise uninstall node
mise uninstall python

Removes all installed versions of a tool.

Update a tool to the latest version

mise upgrade node
mise upgrade python

Updates an installed tool to its latest available version.

Update all installed tools

mise upgrade

Updates all installed tools to their latest available versions.

Setting Versions

Set a global default version for a tool

mise global node 20.10.0
mise global python 3.11.5

Sets the default version for a tool for your user account.

Set a local project version for a tool

mise local node 20.10.0
mise local python 3.11.5

Sets the version for a tool for the current project directory. This creates or updates .mise.toml in the current directory.

Unset a local project version for a tool

mise unset local node
mise unset local python

Removes the version setting for a tool from the local project configuration (.mise.toml).

Unset a global version for a tool

mise unset global node
mise unset global python

Removes the global default version setting for a tool.

List currently active versions

mise current node
mise current python

Shows the version of a tool that is currently active in your shell.

List all currently active versions

mise current

Shows all tools and their currently active versions.

Configuration and Plugins

List installed plugins

mise plugin list

Shows all plugins mise is currently using.

Add a plugin

mise plugin add nodejs https://github.com/mise-plugins/mise-node-plugin.git
mise plugin add python https://github.com/mise-plugins/mise-python-plugin.git

Adds a new plugin from a Git repository.

Remove a plugin

mise plugin remove nodejs
mise plugin remove python

Removes a plugin.

List available plugins

mise plugin list --all

Shows all officially supported plugins that can be added.

Show the configuration file

mise config show

Prints the current mise configuration.

Edit the configuration file

mise config edit

Opens the main configuration file (~/.config/mise/config.toml) in your default editor.

Edit the local configuration file

mise config edit --local

Opens the project-specific configuration file (.mise.toml) in your default editor.

Other Commands

Execute a command with a specific tool version

mise run node@20.10.0 -- node --version
mise run python@3.11.5 -- python --version

Runs a command using a specific version of a tool without changing the active version in your shell.

Display help

mise help
mise help install
mise help local

Shows help information for mise or specific commands.

Rehash shims

mise rehash

Updates the mise shims. This is usually done automatically but can be useful if commands are not found.

Common Patterns

Automatically use project-specific Node.js versions

Ensure you have the nodejs plugin installed:

mise plugin add nodejs https://github.com/mise-plugins/mise-node-plugin.git

Then, in your project directory:

mise local node 20.10.0

Now, whenever you are in this directory or its subdirectories, mise will automatically use Node.js version 20.10.0.

Setting up a new project with a specific Python version

mkdir my-python-project
cd my-python-project
mise local python 3.11.5
python --version # Will show 3.11.5

Running a script with a specific Ruby version without setting it globally or locally

mise run ruby@3.2.2 -- ruby my_script.rb

Using different versions of tools in different projects

Create a .mise.toml file in the root of each project with the desired versions:

# In project-a/.mise.toml
[tools]
node = "18.18.0"
python = "3.10.0"

# In project-b/.mise.toml
[tools]
node = "20.10.0"
ruby = "3.2.2"

mise will automatically switch versions as you cd between these directories.

Installing all tools defined in .mise.toml

If you clone a repository with a .mise.toml file, you can install all the required versions with:

mise install

Gotchas

• Shell Integration: For automatic version switching based on directory, mise needs to be integrated into your shell. The installation script usually handles this, but if mise commands aren’t found or auto-switching doesn’t work, check your shell’s configuration file (e.g., .bashrc, .zshrc) for lines added by mise.
• PATH Order: If you have other version managers or manual installations in your PATH, ensure mise shims are prioritized. This is typically handled by the installation script.
• Plugin Updates: Plugins are not updated automatically by mise upgrade. You might need to mise plugin update <plugin-name> or reinstall the plugin if you encounter issues with specific tool versions.
• mise.toml Location: mise searches for .mise.toml in the current directory and parent directories up to the home directory. If you have multiple .mise.toml files in your hierarchy, the one closest to the current directory takes precedence.
• Network Access for Installation: Installing new tool versions requires internet access to download the necessary binaries.
• Permissions: Ensure mise has write permissions to its installation directories (usually within ~/.local/share/mise or ~/.mise).