Portable package manager for Neovim that runs everywhere Neovim runs.
Easily install and manage LSP servers, DAP servers, linters, and formatters.
:help mason.nvim
Latest version: v2.3.1
Table of Contents
Introduction
:h mason-introduction
mason.nvim is a Neovim plugin that allows you to easily manage external editor tooling such as LSP servers, DAP servers,
linters, and formatters through a single interface. It runs everywhere Neovim runs (across Linux, macOS, Windows, etc.),
with only a small set of external requirements needed.
Packages are installed in Neovim's data directory (:h standard-path) by default. Executables are
linked to a single bin/ directory, which mason.nvim will add to Neovim's PATH during setup, allowing seamless access
from Neovim builtins (LSP client, shell, terminal, etc.) as well as other 3rd party plugins.
For a list of all available packages, see https://mason-registry.dev/registry/list.
Installation & Usage
:h mason-quickstart
Install using your plugin manager of choice. Setup is required:
require("mason").setup()
mason.nvim is optimized to load as little as possible during setup. Lazy-loading the plugin, or somehow deferring the
setup, is not recommended.
Refer to the Configuration section for information about which settings are available.
Recommended setup for lazy.nvim
The following is the recommended setup when using lazy.nvim. It will set up the plugin for you, meaning you don't have
to call require("mason").setup() yourself.
{
"mason-org/mason.nvim",
opts = {}
}
Requirements
:h mason-requirements
mason.nvim relaxes the minimum requirements by attempting multiple different utilities (for example, wget,
curl, and Invoke-WebRequest are all perfect substitutes).
The minimum recommended requirements are:
- neovim
>= 0.10.0
- For Unix systems:
git(1)curl(1) or GNU wget(1)unzip(1)- GNU tar (
tar(1) or gtar(1) depending on platform)
gzip(1)
- For Windows systems:
- pwsh or powershell
- git
- GNU tar
- One of the following:
Note that mason.nvim will regularly shell out to external package managers, such as cargo and npm. Depending on
your personal usage, some of these will also need to be installed. Refer to :checkhealth mason for a full list.
Commands
:h mason-commands
:Mason - opens a graphical status window:MasonUpdate - updates all managed registries:MasonInstall <package> ... - installs/re-installs the provided packages:MasonUninstall <package> ... - uninstalls the provided packages:MasonUninstallAll - uninstalls all packages:MasonLog - opens the mason.nvim log file in a new tab window
Registries
Mason's core package registry is located at mason-org/mason-registry.
Before any packages can be used, the registry needs to be downloaded. This is done automatically for you when using the
different Mason commands (e.g. :MasonInstall), but can also be done manually by using the :MasonUpdate command.
If you're utilizing Mason's Lua APIs to access packages, it's recommended to use the
:h mason-registry.refresh() or :h mason-registry.update()
functions to ensure you have the latest package information before retrieving packages.
Screenshots
Firewall (socket.dev)
Socket Firewall is a free tool that blocks malicious packages at install time, giving developers proactive protection
against rising supply chain attacks.
mason.nvim supports the Socket.dev firewall. To enable the firewall, turn it on in the configuration:
require("mason").setup {
firewall = {
enabled = true
}
}
By default, mason.nvim will automatically install and update the Socket Firewall client. If you want to manage the
client manually, set auto_managed to false (this requires the sfw binary to be available in your PATH):
require("mason").setup {
firewall = {
enabled = true,
auto_managed = false
}
}
For more information refer to the Socket.dev documentation.
[!NOTE]
If you already use the Socket.dev firewall in a proxy service configuration you don't need to enable the firewall in
mason.nvim.
Configuration
:h mason-settings
You may optionally configure certain behavior of mason.nvim when calling the .setup() function. Refer to the
default configuration for a list of all available settings.
Example:
require("mason").setup({
ui = {
icons = {
package_installed = "✓",
package_pending = "➜",
package_uninstalled = "✗"
}
}
})
Configuration using lazy.nvim
{
"mason-org/mason.nvim",
opts = {
ui = {
icons = {
package_installed = "✓",
package_pending = "➜",
package_uninstalled = "✗"
}
}
}
}
Default configuration
---@class MasonSettings
local DEFAULT_SETTINGS = {
---@since 1.0.0
-- The directory in which to install packages.
install_root_dir = path.concat { vim.fn.stdpath "data", "mason" },
---@since 1.0.0
-- Where Mason should put its bin location in your PATH. Can be one of:
-- - "prepend" (default, Mason's bin location is put first in PATH)
-- - "append" (Mason's bin location is put at the end of PATH)
-- - "skip" (doesn't modify PATH)
---@type '"prepend"' | '"append"' | '"skip"'
PATH = "prepend",
---@since 1.0.0
-- Controls to which degree logs are written to the log file. It's useful to set this to vim.log.levels.DEBUG when
-- debugging issues with package installations.
log_level = vim.log.levels.INFO,
---@since 1.0.0
-- Limit for the maximum amount of packages to be installed at the same time. Once this limit is reached, any further
-- packages that are requested to be installed will be put in a queue.
max_concurrent_installers = 4,
---@since 1.0.0
-- [Advanced setting]
-- The registries to source packages from. Accepts multiple entries. Should a package with the same name exist in
-- multiple registries, the registry listed first will be used.
registries = {
"github:mason-org/mason-registry",
},
---@since 2.3.0
-- [Advanced setting]
-- The registries to source system packages from. Accepts multiple entries. Should a package with the same name exist in
-- multiple registries, the registry listed first will be used.
system_registries = {
"github:mason-org/mason-system-registry",
},
registry_cache = {
---@since 2.3.0
-- [Advanced setting]
-- Whether Mason should automatically refresh the registry when needed. If false, the registry will have to be
-- updated manually via :MasonUpdate or the :Mason UI.
refresh = true,
---@since 2.3.0
-- Amount of seconds before the local registry cache is considered stale.
-- Note that this setting has no effect if refresh is set to false.
duration = 24 * 60 * 60, -- 24 hours
},
firewall = {
---@since 2.3.0
-- Whether to enable the socket.dev firewall (sfw) for supported package sources.
-- For more information, refer to https://socket.dev.
enabled = false,
---@since 2.3.0
-- Whether mason.nvim should automatically install and update the Socket Firewall client.
-- If false, the sfw binary must exist in PATH if the firewall is enabled.
auto_managed = true,
},
---@since 1.0.0
-- The provider implementations to use for resolving supplementary package metadata (e.g., all available versions).
-- Accepts multiple entries, where later entries will be used as fallback should prior providers fail.
-- Builtin providers are:
-- - mason.providers.registry-api - uses the https://api.mason-registry.dev API
-- - mason.providers.client - uses only client-side tooling to resolve metadata
providers = {
"mason.providers.registry-api",
"mason.providers.client",
},
github = {
---@since 1.0.0
-- The template URL to use when downloading assets from GitHub.
-- The placeholders are the following (in order):
-- 1. The repository (e.g. "rust-lang/rust-analyzer")
-- 2. The release version (e.g. "v0.3.0")
-- 3. The asset name (e.g. "rust-analyzer-v0.3.0-x86_64-unknown-linux-gnu.tar.gz")
download_url_template = "https://github.com/%s/releases/download/%s/%s",
},
pip = {
---@since 1.0.0
-- Whether to upgrade pip to the latest version in the virtual environment before installing packages.
upgrade_pip = false,
---@since 1.0.0
-- These args will be added to `pip install` calls. Note that setting extra args might impact intended behavior
-- and is not recommended.
--
-- Example: { "--proxy", "https://proxyserver" }
install_args = {},
},
npm = {
---@since 2.3.0
-- These args will be added to `npm install` calls. Note that setting extra args might impact intended behavior
-- and is not recommended.
--
-- Example: { "--registry", "https://registry.npmjs.org/" }
install_args = {},
},
ui = {
---@since 1.0.0
-- Whether to automatically check for new versions when opening the :Mason window.
check_outdated_packages_on_open = true,
---@since 1.0.0
-- The border to use for the UI window. Accepts same border values as |nvim_open_win()|.
-- Defaults to `:h 'winborder'` if nil.
border = nil,
---@since 1.11.0
-- The backdrop opacity. 0 is fully opaque, 100 is fully transparent.
backdrop = 60,
---@since 1.0.0
-- Width of the window. Accepts:
-- - Integer greater than 1 for fixed width.
-- - Float in the range of 0-1 for a percentage of screen width.
width = 0.8,
---@since 1.0.0
-- Height of the window. Accepts:
-- - Integer greater than 1 for fixed height.
-- - Float in the range of 0-1 for a percentage of screen height.
height = 0.9,
icons = {
---@since 1.0.0
-- The list icon to use for installed packages.
package_installed = "◍",
---@since 1.0.0
-- The list icon to use for packages that are installing, or queued for installation.
package_pending = "◍",
---@since 1.0.0
-- The list icon to use for packages that are not installed.
package_uninstalled = "◍",
},
keymaps = {
---@since 1.0.0
-- Keymap to expand a package
toggle_package_expand = "<CR>",
---@since 1.0.0
-- Keymap to install the package under the current cursor position
install_package = "i",
---@since 1.0.0
-- Keymap to reinstall/update the package under the current cursor position
update_package = "u",
---@since 1.0.0
-- Keymap to check for new version for the package under the current cursor position
check_package_version = "c",
---@since 1.0.0
-- Keymap to update all installed packages
update_all_packages = "U",
---@since 1.0.0
-- Keymap to check which installed packages are outdated
check_outdated_packages = "C",
---@since 1.0.0
-- Keymap to uninstall a package
uninstall_package = "X",
---@since 1.0.0
-- Keymap to cancel a package installation
cancel_installation = "<C-c>",
---@since 1.0.0
-- Keymap to apply language filter
apply_language_filter = "<C-f>",
---@since 1.1.0
-- Keymap to toggle viewing package installation log
toggle_package_install_log = "<CR>",
---@since 1.8.0
-- Keymap to toggle the help view
toggle_help = "g?",
},
},
}
👋 didn't find what you were looking for? Try looking in the help docs :help mason.nvim!
它是一个可移植的 Neovim 包管理器：一个插件，通过统一的界面来安装和管理编辑器的外部工具——LSP 服务器、DAP 服务器、代码检查器（linter）和格式化工具（formatter），Neovim 能跑在哪里它就能用在哪里。