- π Intro
- β¨ Features
- π¦ Installation
- π§ Configuration
- βοΈ Basic Usage
- π Plugin Spec
- π» Commands
- π¨ UI
- π Plugin Priority
- π Picker Sources
- π§ͺ Testing
- π£ Self-Promotion
- π¬ Feedback
nvim-plug is an asynchronous Neovim plugin manager written in Lua.
There is also a Chinese introduction about this plugin.
- π Fast β Fully implemented in Lua for minimal overhead and quick startup.
- β‘ Asynchronous Operations β Plugin download and build steps run in parallel using Neovim jobs.
- π Flexible lazy-loading β Load plugins on events, commands, mappings, filetypes, and more.
- π¦ LuaRocks Integration β Install and manage LuaRocks dependencies seamlessly alongside plugins.
- π¨ Custom UI β Provides an extensible UI API for building your own installation/update interface.
To install nvim-plug automatically:
local dir = vim.fs.joinpath(vim.fn.stdpath('data'), 'repos/')
local function bootstrap(repo)
if vim.fn.isdirectory(dir .. repo) == 0 then
vim.fn.system({
'git',
'clone',
'--depth',
'1',
'https://github.com/' .. repo .. '.git',
dir .. repo,
})
end
vim.opt.runtimepath:append(dir .. repo)
end
bootstrap('wsdjeg/job.nvim')
bootstrap('wsdjeg/logger.nvim')
bootstrap('wsdjeg/nvim-plug')Using LuaRocks:
luarocks install nvim-plugThe following shows every option with its default value.
require('plug').setup({
-- directory plugins are cloned into
bundle_dir = vim.fs.joinpath(vim.fn.stdpath('data'), 'repos'),
-- directory raw plugins are downloaded into
raw_plugin_dir = vim.fs.joinpath(
vim.fn.stdpath('data'),
'repos/raw_plugin'
),
-- max number of concurrent jobs
max_processes = 5,
base_url = 'https://github.com',
-- 'default' (Vundle-style window), 'notify' (requires wsdjeg/notify.nvim),
-- or a function(name, data) for a custom UI. See `Custom Plugin UI` below.
ui = 'default',
-- proxy for git/curl jobs, default: nil
http_proxy = nil,
-- default: nil
https_proxy = nil,
-- default `git clone` depth, 0 disables `--depth`
clone_depth = 1,
-- load plugins ordered by priority, needs plug.load()
enable_priority = false,
-- focus the UI window when it is opened
focus_window = false,
-- directory name used to auto-load plugin specs
import = 'plugins',
-- enable LuaRocks support
enable_luarocks = false,
-- development directory for local plugins, default: nil
dev_path = nil,
})setup() only touches the keys you pass, and falsy values such as false
or 0 are honoured β calling setup() twice does not wipe earlier values:
require('plug').setup({ enable_priority = true })
require('plug').setup({ enable_priority = false }) -- really turns it offrequire('plug').add({
{
'wsdjeg/scrollbar.vim',
events = { 'VimEnter' },
},
{
'wsdjeg/vim-chat',
enabled = function()
return vim.fn.has('nvim-0.10.0') == 1
end,
},
{
'wsdjeg/flygrep.nvim',
cmds = { 'FlyGrep' },
config = function()
require('flygrep').setup()
end,
},
{
-- a raw plugin without a repo name: `url` defines both source and name
type = 'raw',
url = 'https://gist.githubusercontent.com/wsdjeg/4ac99019c5ca156d35704550648ba321/raw/4e8c202c74e98b5d56616c784bfbf9b873dc8868/markdown.vim',
script_type = 'after/syntax',
},
{
'D:/wsdjeg/winbar.nvim',
events = { 'VimEnter' },
},
{
'wsdjeg/vim-mail',
on_func = 'mail#',
},
})The default import option is plugins which means nvim-plug will load PluginSpec automatically
from plugins directory in runtimepath.
To use this option, you need to call plug.load() function.
Example structure:
~/.config/nvim/
βββ init.lua
βββ plugins/
βββ colorscheme.lua
βββ lsp.lua
βββ completion.lua
Each file in the plugins/ directory should return a PluginSpec table:
-- plugins/colorscheme.lua
return {
'rakr/vim-one',
priority = 100,
config = function()
vim.cmd('colorscheme one')
end,
}Or return a list of PluginSpec:
-- plugins/lsp.lua
return {
{
'neovim/nvim-lspconfig',
events = { 'BufReadPre' },
},
{
'hrsh7th/nvim-cmp',
events = { 'InsertEnter' },
},
}Then in your init.lua:
require('plug').setup({
import = 'plugins', -- default value
enable_priority = true,
})
require('plug').load()A single spec file that fails to load (a syntax error, a bad return value) is
logged and skipped, so the remaining files are still registered. Set
import = nil to disable auto-loading entirely.
You can use nvim-plug to manage itself:
local dir = 'D:/bundle_dir/wsdjeg/nvim-plug'
if vim.fn.isdirectory(dir) == 0 then
vim.fn.system({
'git',
'clone',
'--depth',
'1',
'https://github.com/wsdjeg/nvim-plug.git',
dir,
})
end
vim.opt.runtimepath:append(dir)
require('plug').setup({
bundle_dir = 'D:/bundle_dir',
})
require('plug').add({
{
'wsdjeg/nvim-plug',
fetch = true,
},
})nvim-plug supports installing and managing LuaRocks packages alongside regular plugins.
First, enable LuaRocks support in your configuration:
require('plug').setup({
enable_luarocks = true,
})Then add LuaRocks packages to your plugin list:
require('plug').add({
{
'example/lua-package',
type = 'rocks', -- specify this is a LuaRocks package
},
})The installed rock list is cached, so luarocks list runs once per session
rather than once per plugin.
Note: LuaRocks packages are installed serially due to limitations in LuaRocks itself (see luarocks/luarocks#1359).
The plugin spec is inspired by dein.nvim.
| Name | Description |
|---|---|
[1] |
(string) plugin repo short name, e.g. wsdjeg/flygrep.nvim. Optional when url is set |
autoload |
(boolean) load plugin after git clone (default: true for git plugins, false for raw plugins) |
branch |
(string) specify a git branch |
build |
(string|string[]) custom build command executed by job.nvim |
cmds |
(string|string[]) commands lazy loading |
config_after |
(function) function called after loading files in plugin/ directory |
config_before |
(function) function called after running plug.add() |
config |
(function) function called after adding plugin path to Neovim's runtimepath, before loading files in plugin/ directory |
depends |
(PluginSpec[]) a list of dependencies for a plugin |
desc |
(string) short description of the plugin |
dev |
(boolean) default is false. If true, then dev path will be used instead of bundle path |
dev_path |
(string) development directory for this plugin (auto-set when dev = true) |
enabled |
(boolean|function) evaluated when startup. If false the plugin will be skipped |
events |
(string|string[]) events to lazy-load the plugin |
fetch |
(boolean) if set to true, nvim-plug won't add the path to user runtimepath. Useful to manage no-plugin repositories |
frozen |
(boolean) update only when specific with Plug update name |
keys |
(table) key bindings for this plugin, set immediately when the plugin is added. See Notes |
module |
(string) Lua module name (auto-inferred from plugin name, used with opts) |
on_ft |
(string|string[]) filetypes lazy loading |
on_func |
(string|string[]) Vim function lazy loading |
on_map |
(string|string[]) keybindings lazy loading |
opts |
(table) setup options for the plugin (passed to require(module).setup(opts)) |
priority |
(integer) set the order in which plugins are loaded, default: 50 |
script_type |
(string) plugin type including color, plugin, none, etc. |
tag |
(string) specific Git tag |
url |
(string) upstream URL. Overrides the URL derived from [1], and makes [1] optional |
type |
('git'|'rocks'|'raw') specific plugin type. If it is raw then script_type must be set |
-
[1]may be omitted whenurlis given. The plugin name is then derived from the last segment ofurl:require('plug').add({ { type = 'raw', url = 'https://example.com/syntax/markdown.vim', script_type = 'after/syntax', -- name: 'markdown.vim' }, })
-
configandconfig_afterwill not be called until the plugin has been installed. -
prioritydoes not work for lazy plugins. -
If
devistrueand the development directory exists, it will be added to runtimepath instead of the bundle path. -
keysis not lazy mapping - keys are set immediately when the plugin is added. Useon_mapfor lazy loading. Both forms below are accepted, and the mode defaults ton:-- implicit mode keys = { { '<F5>', '<cmd>write<cr>' } } -- explicit mode keys = { { 'n', '<F5>', '<cmd>write<cr>', { desc = 'save' } } }
-
optsprovides a convenient way to callsetup()on a plugin. It requires the plugin to export asetup()function. -
moduleis auto-inferred from the plugin name (e.g.,flygrep.nvimβflygrep). You can override it if needed. -
dependsis resolved before the plugin itself. A dependency cycle (adepends onb,bdepends ona, or a spec depending on itself) is detected and registered only once instead of recursing forever.
The opts field provides a shorthand for plugin configuration:
-- Using opts
require('plug').add({
{
'wsdjeg/flygrep.nvim',
opts = {
enable = true,
timeout = 1000,
},
},
})
-- Equivalent to:
require('plug').add({
{
'wsdjeg/flygrep.nvim',
config = function()
require('flygrep').setup({
enable = true,
timeout = 1000,
})
end,
},
})require('plug').setup({
dev_path = '~/projects', -- your development directory
})
require('plug').add({
{
'wsdjeg/flygrep.nvim',
dev = true, -- will use ~/projects/flygrep.nvim instead of bundle_dir
},
})type |
Installed by | Notes |
|---|---|---|
git (default) |
git clone / git pull |
Path built from bundle_dir and the repo name |
rocks |
luarocks install |
Serialized, needs enable_luarocks = true |
raw |
curl |
Needs script_type; downloaded under raw_plugin_dir |
A local directory (an absolute path that exists on disk) is detected automatically and never cloned or updated.
nvim-plug provides the following commands:
| Command | Description |
|---|---|
:Plug install [plugin...] |
Install specific plugin(s) or all plugins |
:Plug update [plugin...] |
Update specific plugin(s) or all plugins |
:PlugInstall [plugin...] |
(Deprecated) Same as :Plug install |
:PlugUpdate [plugin...] |
(Deprecated) Same as :Plug update |
Both commands complete plugin names on <Tab>.
Note: :PlugInstall and :PlugUpdate are deprecated and will be removed in v1.0.0. Use :Plug install and :Plug update instead.
" Install all plugins
:Plug install
" Install specific plugin
:Plug install flygrep.nvim
" Update all plugins
:Plug update
" Update specific plugin (ignores frozen status)
:Plug update flygrep.nvimThe default UI is inspired by Vundle.vim.
Its status is reset at the start of every install/update run, so the
window only ever shows the plugins of the current run.
The default highlight groups are:
| Highlight Group Name | Default Link | Description |
|---|---|---|
PlugTitle |
TODO |
the first line of plugin window |
PlugProcess |
Repeat |
the downloading progress |
PlugDone |
Type |
clone/build/install done |
PlugFailed |
WarningMsg |
clone/build/install failed |
PlugDoing |
Number |
job is running |
To change the default highlight group:
-- In Lua
vim.api.nvim_set_hl(0, 'PlugTitle', { default = true, link = 'TODO' })
vim.api.nvim_set_hl(0, 'PlugProcess', { default = true, link = 'Repeat' })
vim.api.nvim_set_hl(0, 'PlugDone', { default = true, link = 'Type' })
vim.api.nvim_set_hl(0, 'PlugFailed', { default = true, link = 'WarningMsg' })
vim.api.nvim_set_hl(0, 'PlugDoing', { default = true, link = 'Number' })" In Vimscript
hi def link PlugTitle TODO
hi def link PlugProcess Repeat
hi def link PlugDone Type
hi def link PlugFailed WarningMsg
hi def link PlugDoing NumberYou can also change the UI to notify, provided by wsdjeg/notify.nvim.
The backend is resolved on every notification, so installing notify.nvim later
works without restarting; when it is missing, vim.notify is used instead.
local dir = vim.fs.joinpath(vim.fn.stdpath('data'), 'repos/')
local function bootstrap(repo)
if vim.fn.isdirectory(dir .. repo) == 0 then
vim.fn.system({
'git',
'clone',
'--depth',
'1',
'https://github.com/' .. repo .. '.git',
dir .. repo,
})
end
vim.opt.runtimepath:append(dir .. repo)
end
bootstrap('wsdjeg/job.nvim')
bootstrap('wsdjeg/logger.nvim')
bootstrap('wsdjeg/notify.nvim')
bootstrap('wsdjeg/nvim-plug')
require('plug').setup({
ui = 'notify',
})
require('plug').add({
{
'wsdjeg/notify.nvim',
fetch = true,
},
{
'wsdjeg/nvim-plug',
fetch = true,
},
})Every finished operation is reported, including failures:
alpha.nvim installed
beta.nvim failed to update
gamma.nvim luarocks install failed
Progress-only updates (e.g. clone_process) stay silent on purpose.
To setup custom UI, pass a function as ui. It receives two parameters:
name(string) - plugin nameplugUiData(see below) - plugin status data
plugUiData is table with following keys:
| Key | Type | Description |
|---|---|---|
command |
string |
Current operation: 'clone', 'pull', 'curl', 'build', 'luarocks' |
build_done |
boolean |
Build completed successfully |
building |
boolean |
Build is in progress |
clone_done |
boolean |
git clone completed successfully |
clone_process |
string |
git clone progress, e.g., 16% (160/1000) |
curl_done |
boolean |
Download completed successfully |
download_process |
number |
Download percentage, 100 once the clone finished |
is_local |
boolean |
Plugin is a local plugin (skipped) |
luarocks_done |
boolean |
LuaRocks installation completed |
pull_done |
boolean |
git pull completed successfully |
pull_process |
string |
git pull progress information |
The callback is looked up on every update, so changing ui after setup()
takes effect immediately.
--- your custom UI
local function on_ui_update(name, data)
-- `clone_done == false` is a real value: check it explicitly, otherwise
-- failures are silently dropped
if data.command == 'clone' then
if data.clone_done then
print(string.format('β %s installed', name))
elseif data.clone_done == false then
print(string.format('β %s failed to install', name))
end
elseif data.command == 'pull' then
if data.pull_done then
print(string.format('β %s updated', name))
elseif data.pull_done == false then
print(string.format('β %s failed to update', name))
end
elseif data.command == 'build' and data.build_done == false then
print(string.format('β %s failed to build', name))
end
end
require('plug').setup({
ui = on_ui_update,
})By default this feature is disabled. Plugins will be loaded when running add().
To enable the plugin priority feature, you will have to run plug.load() after executing plug.add().
This option is not available for lazy-loading plugins!
For example:
require('plug').setup({
max_processes = 5,
enable_priority = true,
})
require('plug').add({
{
'wsdjeg/scrollbar.vim',
events = { 'VimEnter' },
},
{
'wsdjeg/vim-chat',
enabled = function()
return vim.fn.has('nvim-0.10.0') == 1
end,
},
{
'wsdjeg/flygrep.nvim',
cmds = { 'FlyGrep' },
config = function()
require('flygrep').setup()
end,
},
{
'rakr/vim-one',
priority = 100,
config = function()
vim.cmd('colorscheme one')
end,
},
})
require('plug').load()Plugins with higher priority values are loaded first. Default priority is 50.
nvim-plug also provides a source for picker.nvim,
which can be opened with :Picker plug.
| Key Binding | Handler | Description |
|---|---|---|
<C-t> |
default_action |
open floating terminal in the plugin directory. Requires terminal.nvim. |
<C-b> |
_open_url |
open the URL of the selected plugin via default browser. |
<C-y> |
_copy_url |
copy the URL of the selected plugin into the " register. |
<Enter> |
_tabnew_lcd |
create a new tab and change directory to the plugin root |
The directory used is the dev path for dev plugins, the runtime path for
installed rocks, and the clone path otherwise. Pressing <Enter> on a plugin
that is not installed yet reports a warning instead of opening an empty tab.
The test suite uses luaunit and runs headless:
# run everything (dependencies are installed automatically)
make test
# run a subset, shorthand expands to test/**/*<pattern>*_spec.lua
make test PATTERN=loader
# or pass a full path
make test PATTERN=test/picker_spec.luaTest dependencies (luaunit and a job.nvim mock) are downloaded into
test/.deps/ by test/install_deps.lua, which is cross-platform.
Like this plugin? Star the repository on GitHub.
Love this plugin? Follow me on GitHub.
If you encounter any bugs or have suggestions, please file an issue in the issue tracker.

