Plugins

Plugins add installation logic, environment directives, or bootstrap package managers to mise. Most tools can use a built-in backend directly, even when they have no registry shorthand. Start there before installing a plugin.

For release binaries, prefer packslip when the publisher provides signed manifests, then aqua, github, or gitlab. Use a plugin when your integration needs custom behavior those backends cannot provide.

Plugin code can read files, make requests, and run processes with your permissions. Lua's cross-platform runtime does not make a plugin an OS sandbox. Review the source and its updates; new asdf and vfox tool plugins are not accepted into the mise registry.

Choose a plugin type

Type	Use it for	Configuration	Author guide
Backend	Several versioned tools managed by one integration	[tools], my-backend:tool	Backend development
Tool	One versioned tool with download/install hooks	[tools], the installed plugin name	Tool development
Environment	Variables or PATH entries without a tool installation	[env], _.my-plugin	Environment development
Package	Host-managed packages for machine bootstrap	[bootstrap.packages]	Package development
asdf	An existing shell-based tool integration	[tools], an asdf backend	Legacy plugins

Register a package manager in [bootstrap.plugins], or install it as package:<name>, before declaring its requests in [bootstrap.packages]. See the package plugin setup for a complete configuration.

The Lua runtime is available on Windows, macOS, and Linux. Each plugin must still support the selected platform and any external programs it invokes. asdf plugins use shell scripts and are disabled by default on Windows.

Backend Plugins

A backend plugin implements BackendListVersions, BackendInstall, and BackendExecEnv. The prefix is the name under which you install the plugin:

# Replace this example repository and tool with your plugin's values.
mise plugin install my-backend https://github.com/your-org/my-backend
mise use my-backend:some-tool@1.0.0
mise exec -- some-tool --version

See Using Plugins for installation, local development, and updates. The backend template provides a starting point.

Tool Plugins

A tool plugin manages one tool through hooks such as Available, PreInstall, and EnvKeys. Use its installed name as the tool name:

mise plugin install my-tool https://github.com/your-org/my-tool-plugin
mise use my-tool@1.0.0
mise exec -- my-tool --version

These repository and executable names are placeholders. Start with the tool template when writing your own.

Environment Plugins

An environment plugin implements MiseEnv and optionally MisePath. Install it before using its directive:

mise plugin install my-env-plugin https://github.com/your-org/my-env-plugin

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

The fields are defined by the plugin. See environment plugin development for return values, cache behavior, and the environment template.

Package plugins

Package plugins implement a host package manager for bootstrap packages. They operate on batches of package requests and report installed state. Their installations belong to the host manager, unlike versioned tools stored under mise's data directory. See Package Plugin Development for the hook contract.

General Plugin Usage

Using Plugins explains repository URLs, archive installation, local links, pinning plugin revisions, and diagnostics. List what is already installed with:

mise plugins ls --urls

asdf (Legacy) Plugins

mise can run existing asdf plugins with scripts such as bin/list-all, bin/install, and bin/exec-env. Use the legacy guide to maintain one, or the hook migration table to port it to Lua.

Plugin Authors

The mise-plugins organization hosts community plugins. Contact the maintainers through a GitHub discussion to discuss hosting. Hosting a plugin and adding a registry shorthand are separate decisions; see the publishing guide.

Tool Options

Plugins define custom options in their tool configuration. For example, a plugin that supports a mirror option could accept:

[tools]
my-tool = {
  version = "1.0.0",
  mirror = "https://mirror.example.com",
}

For asdf and version-specific vfox lifecycle hooks, that option is exposed as MISE_TOOL_OPTS__MIRROR. These variables are scoped to hook execution, not exported into your shell. mise-managed fields such as depends, install_env, and os are handled by mise instead. Backend plugin hooks receive typed options through ctx.options, including arrays and nested tables; see backend context.

Templates

Repository values in [plugins] support templates. Prefer a normal SSH or HTTPS repository URL and your Git credential setup for private repositories; embedding credentials in a URL can expose them in configuration or logs.

[plugins]
my-backend = "git@github.com:your-org/my-backend.git"