Plugins

Plugins extend mise with new functionality, such as extra tools or environment variable management.

Historically, plugins were the only way to add new tools, since the only backend was asdf.

With that backend, every tool has its own plugin, which must be installed manually. Now, with core tools and backends like aqua/github, plugins are no longer necessary to run most tools in mise.

Tool plugins should be avoided for security reasons. New tools built with asdf/plugins will not be accepted into mise unless they are very popular and aqua/github is not an option for some reason.

The exception is a tool that needs to set env vars or has a complex installation process: plugins can provide functionality like setting env vars globally without relying on a tool being installed. They can also provide aliases for versions.

To integrate a new tool into mise, either get it into the aqua registry or check whether it can be installed with github. Aqua is preferred over github: it has better UX and more features, such as SLSA verification and the ability to use different logic for older versions.

You can manage all installed plugins in mise with mise plugins.

mise plugins ls --urls
# Plugin                          Url                                                     Ref  Sha
# 1password                       https://github.com/mise-plugins/mise-1password-cli.git  HEAD f5d5aab
# vfox-mise-plugins-vfox-dart     https://github.com/mise-plugins/vfox-dart               HEAD 1424253
# ...

Backend Plugins

Backend plugins provide enhanced functionality with modern backend methods. These plugins use the plugin:tool format and offer advantages over traditional plugins:

• Multiple Tools: A single plugin can manage multiple tools
• Enhanced Methods: Backend methods for listing versions, installing, and setting environment variables
• Cross-platform: Work on Windows, macOS, and Linux
• Performance: Faster execution than shell-based plugins

Example usage:

# Install a backend plugin
mise plugin install my-plugin https://github.com/username/my-plugin

# Use the plugin:tool format
mise install my-plugin:some-tool@1.0.0
mise use my-plugin:some-tool@latest

See Backend Plugin Development for creating backend plugins. You can start quickly with the mise-backend-plugin-template.

Tool Plugins

Tool plugins use the traditional hook-based approach with Lua scripts. These plugins provide:

• Hook-based: Use hooks like PreInstall, PostInstall, Available, etc.
• Single Tool: Each plugin manages one tool
• Cross-platform: Work on Windows, macOS, and Linux
• Flexible: Full control over installation and environment setup

Example usage:

# Install a tool plugin
mise plugin install my-tool https://github.com/username/my-tool-plugin

# Use the tool directly
mise install my-tool@1.0.0
mise use my-tool@latest

See Tool Plugin Development for creating tool plugins. The mise-tool-plugin-template provides a ready-to-use starting point.

Environment Plugins

Environment plugins provide environment variables and PATH modifications without managing tool versions. They're ideal for integrating with secret managers, setting dynamic configurations, and standardizing team environments.

Example usage:

# Install an environment plugin
mise plugin install my-env-plugin https://github.com/username/my-env-plugin

# Configure in mise.toml
[env]
_.my-env-plugin = { api_url = "https://api.example.com", debug = true }

Unlike tool plugins, environment plugins:

• Only implement environment hooks (MiseEnv, MisePath)
• Are activated via env._.<plugin-name> syntax
• Don't manage tool versions or installations

See Environment Plugin Development for creating environment plugins. The mise-env-plugin-template repository provides a ready-to-use starting point.

General Plugin Usage

For end-user documentation on installing and using both backend and tool plugins, see Using Plugins.

asdf (Legacy) Plugins

mise can use asdf's plugin ecosystem under the hood for backward compatibility. These plugins contain shell scripts like bin/install (for installing) and bin/list-all (for listing all available versions).

asdf plugins have limitations compared to modern backends and should only be used when necessary. They only work on Linux/macOS and are slower than native backends.

See asdf (Legacy) Plugins for comprehensive documentation on using and creating these plugins.

Plugin Authors

https://github.com/mise-plugins is a GitHub organization for community-developed plugins. See SECURITY.md for more details on how plugins here are treated differently.

If you'd like your plugin to be hosted here, let me know (a GH discussion or Discord message is fine) and I'd be happy to host it for you.

Tool Options

mise supports "tool options": configuration specified in mise.toml that changes the behavior of tools. One example is virtualenv for Python:

[tools]
python = { version='3.11', virtualenv='.venv' }

WARNING

The python virtualenv tool option is deprecated and will be removed in a future release. Use _.python.venv in the [env] section instead.

For asdf plugins and version-specific vfox lifecycle hooks, this is passed as MISE_TOOL_OPTS__VIRTUALENV=.venv. These variables are scoped to the plugin hook environment; mise does not export them to the user's shell. Custom backend options are passed to the plugin in that format; mise-managed fields such as depends, install_env, and os are not exported.

Currently, this only supports simple strings, but we can make it compatible with more complex types (arrays, tables) fairly easily if there is a need for it.

Templates

Plugin custom repository values can be templates; see Templates for details.

[plugins]
"vfox-backend:my-plugin" = "https://{{ get_env(name='GIT_USR', default='empty') }}:{{ get_env(name='GIT_PWD', default='empty') }}@github.com/foo/my-plugin.git"