Using Plugins

mise supports plugins that extend its functionality, allowing you to install tools that aren't available in the standard registry. This is particularly useful for:

• Installing tools from private repositories
• Using experimental or niche tools
• Creating custom tool installations for your team

What Are Plugins?

Plugins are extensions that can install and manage tools not included in mise's built-in registry. They are written in Lua and come in two main types:

Backend Plugins

Backend plugins use enhanced backend methods and support the plugin:tool format:

• Multiple Tools: A single plugin can manage multiple tools
• Enhanced Methods: Backend methods for listing, installing, and environment setup
• Format: Use the plugin:tool format (e.g., vfox-npm:prettier)

Tool Plugins

Tool plugins use the traditional hook-based approach:

• Single Tool: Each plugin manages one tool
• Hook-based: Use hooks like PreInstall, PostInstall, Available, etc.
• Format: Use the tool name directly (e.g., my-tool)

Both types:

• Install tools from any source (npm packages, GitHub releases, custom builds)
• Set up environment variables and PATH entries
• Handle version management and listing
• Work across all platforms (Windows, macOS, Linux)

Installing Plugins

From a Git Repository

# Install a plugin from a repository
mise plugin install <plugin-name> <repository-url>

# Example: Installing the vfox-npm plugin
mise plugin install vfox-npm https://github.com/jdx/vfox-npm

From Zip File

# Install a plugin from a zip file over HTTPS
mise plugin install <plugin-name> <zip-url>

# Example: Installing a plugin from a zip file
mise plugin install tiny https://github.com/mise-plugins/mise-tiny.git

From Local Directory

# Link a local plugin for development
mise plugin link <plugin-name> /path/to/plugin/directory

Using Plugins (Advanced)

Once a plugin is installed, you can use it with the plugin:tool format:

# Install a specific tool using the plugin
mise install vfox-npm:prettier@latest

# Use the tool
mise use vfox-npm:[email protected]

# Execute the tool
mise exec vfox-npm:prettier -- --version

# List available versions
mise ls-remote vfox-npm:prettier

Plugin:Tool Format

The plugin:tool format allows a single plugin to manage multiple tools. This is particularly useful for:

• Package managers: Install different npm packages, Python packages, etc.
• Tool families: Manage related tools from the same ecosystem
• Custom builds: Install different variants of the same tool

Example: npm packages

# Install different npm packages using the same plugin
mise install vfox-npm:prettier@latest
mise install vfox-npm:[email protected]
mise install vfox-npm:typescript@latest

# Use them in your project
mise use vfox-npm:prettier@latest vfox-npm:[email protected]

Managing Plugins

List installed plugins

# Show all plugins
mise plugins ls

# Show plugin URLs
mise plugins ls --urls

Update plugins

# Update a specific plugin
mise plugin update vfox-npm

# Update all plugins
mise plugin update --all

Remove plugins

# Remove a plugin
mise plugin remove vfox-npm

# This will also remove all tools installed by the plugin

Configuration

Plugins can be configured in your mise.toml file:

[plugins]
vfox-npm = "https://github.com/jdx/vfox-npm"

[tools]
"vfox-npm:prettier" = "latest"
"vfox-npm:eslint" = "8.0.0"

Finding Plugins

While mise doesn't have a centralized registry for community plugins, you can find them:

• GitHub: Search for repositories with "vfox-" prefix
• Community: Check mise community discussions and Discord
• Company internal: Your organization may have private plugins

Plugin Examples

vfox-npm (Example Plugin)

The vfox-npm plugin demonstrates how to create a plugin that installs npm packages:

# Install the plugin
mise plugin install vfox-npm https://github.com/jdx/vfox-npm

# Install tools
mise install vfox-npm:prettier@latest
mise install vfox-npm:eslint@latest

# Use them
mise use vfox-npm:prettier@latest
mise exec vfox-npm:prettier -- --check .

INFO

This is just an example plugin for testing. mise already has built-in npm support that you should use instead: mise install npm:prettier@latest

Backend Plugins (Advanced)

Backend plugins use enhanced backend methods that provide better performance and support for the plugin:tool format:

• BackendListVersions: Lists available versions of a tool
• BackendInstall: Installs a specific version
• BackendExecEnv: Sets up environment variables

This architecture allows plugins to manage multiple tools efficiently while providing a consistent interface.

Tool Plugins (Advanced)

Tool plugins use the traditional hook-based approach:

• Available: Lists available versions
• PreInstall/PostInstall: Installation hooks
• EnvKeys: Environment variable setup
• Parse: Version parsing and validation

Both architectures provide a flexible plugin system that can handle diverse installation and management needs.

Security Considerations

DANGER

When using plugins, be aware that:

• Plugins execute arbitrary code during installation and use
• Only install plugins from trusted sources
• Review plugin code before installation when possible
• Use version pinning to avoid unexpected updates like mise.lock

Troubleshooting

Plugin installation fails

# Check if the repository URL is correct
mise plugin install vfox-npm https://github.com/jdx/vfox-npm

# Check plugin directory
ls ~/.local/share/mise/plugins/

Tool installation fails

# Check plugin logs
mise install vfox-npm:prettier@latest --verbose

# Verify plugin is installed
mise plugins ls

Environment issues

# Check if PATH is set correctly
mise exec vfox-npm:prettier env | grep PATH

# Verify tool is installed
ls ~/.local/share/mise/installs/vfox-npm/prettier/

Next Steps

• Learn how to create backend plugins
• Learn how to create tool plugins
• Explore built-in backends
• Check the community registry