docs/plugin-usage.md
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:
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 use enhanced backend methods and support the plugin:tool format:
plugin:tool format (e.g., vfox-npm:prettier)Tool plugins use the traditional hook-based approach:
PreInstall, PostInstall, Available, etc.my-tool)Both types:
# 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
# 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
# Link a local plugin for development
mise plugin link <plugin-name> /path/to/plugin/directory
Local plugins can also be declared in mise.toml:
[plugins]
my-plugin = "./plugins/my-plugin"
Absolute paths and ~/... are supported. Explicit relative paths beginning with
./ or ../ are resolved from the config root of the file containing the
declaration. Mise symlinks the directory just like mise plugins link, so local
edits are reflected immediately. Existing plugin installations are not replaced
automatically; use mise plugins install --force my-plugin when changing an
existing installation to a local source.
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
The plugin:tool format allows a single plugin to manage multiple tools. This is particularly useful for:
# 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]
# Show all plugins
mise plugins ls
# Show plugin URLs
mise plugins ls --urls
# Update a specific plugin
mise plugin update vfox-npm
# Update all plugins
mise plugin update --all
# Remove a plugin
mise plugin remove vfox-npm
# This will also remove all tools installed by the plugin
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"
While mise doesn't have a centralized registry for community plugins, you can find them:
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 use enhanced backend methods that provide better performance and support for the plugin:tool format:
This architecture allows plugins to manage multiple tools efficiently while providing a consistent interface.
Tool plugins use the traditional hook-based approach:
Both architectures provide a flexible plugin system that can handle diverse installation and management needs.
::: danger When using plugins, be aware that:
mise.lock
:::# 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/
# Check plugin logs
mise install vfox-npm:prettier@latest --verbose
# Verify plugin is installed
mise plugins ls
# 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/