Evgeni Chasnovski

A Guide to vim.pack (Neovim built-in plugin manager)

Evgeni Chasnovski — Fri, 13 Mar 2026 00:00:00 GMT

The upcoming Neovim 0.12 release will have a built-in plugin manager. It is implemented in Lua and is available as a built-in vim.pack module (hence the name). This blog post describes the fundamentals of how vim.pack is intended to be used. Reading only selected sections should be fine, but it is written to be read from top to bottom.

Note

Beware that, although unlikely, some information from this post can become outdated. Neovim’s own documentation is always the higher authority. From the running Neovim instance execute :h vim.pack to read the help and :h vim.pack-examples to read suggested workflows for common use cases.

If you are a visual learner or want to see how using vim.pack looks like, check out this YouTube video:

A Demo of vim.pack (Neovim built-in plugin manager)

Concepts

This section lists vim.pack adjacent information that would be beneficial to understand before using it.

Lua

The vim.pack module is written and is designed to be used in Lua programming language. So at least a basic understanding of its logic and syntax would be useful.

There are many sources online for the language itself, like “Learn X in Y minutes where X=Lua”. Neovim has its own resources: :h lua-concepts and :h lua-guide.

The basic working knowledge to know for vim.pack is about:

Tables: { 'one', 'two' } and { a = 1, b = 2 }.
Functions: f({ 'one', 'two' }).
How to execute code inside user’s config: put it in or source from ‘init.lua’ file.

Runtime files

To provide extensibility and flexibility, Neovim (and Vim) has a concept of runtime files: various support files that can be found and used when Neovim is running. Where these files are searched is controlled by the ‘runtimepath’ option, which is essentially a list of directories.

Most commonly used types of runtime files when it comes to external plugins in Neovim are:

Lua modules. Searched in lua/ subdirectories.
Plugin scripts. Searched in plugin/ subdirectories.
Filetype plugins. Searched in ftplugin/ subdirectories.

For example, if 'runtimepath' is /home/user/dir,/home/user/dir-other, then:

require('myplug') will try to look for lua/myplug.lua or lua/myplug/init.lua inside /home/user/dir, then /home/user/dir-other, and source the first one it finds.
All files in /home/user/dir/plugin and /home/user/dir-other/plugin are sourced in alphabetical order during startup.
Setting filetype myft will look for ftplugin/myft.{vim,lua} inside /home/user/dir, then /home/user/dir-other, and source all that it finds.

The most important runtime paths for common users available by default are:

User’s config directory: ~/.config/nvim on Unix and ~/AppData/Local/nvim on Windows. Used for personal config. This is also known as “config” standard path.
The site/ subdirectory of user’s data directory: ~/.local/share/nvim/site on Unix and ~/AppData/Local/nvim-data/site on Windows. Used for data from plugins installed by user. The parent of site directory is also known as “data” standard path.
The after/ subdirectory of user’s config directory. Primarily used for manual runtime files that should have the “final say” over all others, as it is usually the last ‘runtimepath’ entry.

When it comes to a plugin manager:

Installing a plugin means to download and put it in the known location on the disk.
Loading a plugin means to make sure that its path is a proper part of 'runtimepath'. Not at the start (where user’s config directory should be), not at the end (where user’s after/ config subdirectory should be), but somewhere in the middle.

Plugin packages

To at least somehow standardize extensibility via plugins, Neovim (and Vim) has the concept of plugin packages (a.k.a. “Vim packages” or just “packages”). It is a collection of plugins meant to be used together. For Neovim to find a plugin package, it should be put in ‘pack’ subdirectory of any path from 'packpath' (works similar and by default is equal to 'runtimepath').

One package can have two types of plugins:

So called “opt” plugins are meant to be available/loaded only on demand after executing :packadd. This command searches through a dedicated set of directories (controlled by ‘packpath’ option).
So called “start” plugins are meant to be available/loaded automatically during startup. The only way to make them not load during startup is to move them to the “opt” part of the package.

For example, a package named bundle (common name from early days of adapting this feature) might have the following structure:

bundle/
├── start/                 Directory for "start" plugins
│   ├── plug-one/          First "start" plugin
│   │   └── ftplugin/
│   │       └── myft.lua
│   └── plug-two/          Second "start" plugin
│       └── lua/
│           └── myplug.lua
└── opt/                   Directory for "opt" plugins
    └── plug-three/        The only "opt" plugin
        └── lua/
            └── three.lua

If this package is put as pack/bundle/ subdirectory under some known package path (the ~/.local/share/nvim/site would be the most expected place), then:

Plugins ‘plug-one’ and ‘plug-two’ will always be available after startup.
Plugin ‘plug-three’ is made available after executing :packadd plug-three.

Install and load

Adding plugin(s) to a config is done via vim.pack.add(). It acts as a “smart :packadd” - install if plugin is missing and load it. The design is for it to be a part of the user’s config: add with a list of all external plugins you want to use and forget about it. Like this (for more comprehensive examples see “Config organization”):

vim.pack.add({
  'https://github.com/nvim-mini/mini.nvim',
  'https://github.com/neovim/nvim-lspconfig',
  'https://github.com/nvim-treesitter/nvim-treesitter',
})

By default during initial install there is also a confirmation dialog showing which plugins are going to be installed. Press y to confirm, n to skip, a to allow for all vim.pack.add() confirmations in current session. It looks like this:

Adding a plugin via vim.pack.add() makes it “active” or “loaded” in current session.

All plugins that were not previously installed by vim.pack are installed in parallel. They are put into a dedicated core plugin package as “opt” plugins (see :h vim.pack-directory). There is no “start” plugin support because:

It makes it possible to comment out the (part of) vim.pack.add() call and some plugins will not load in the next session. Almost as if they don’t exist at all.
This way the entire config acts as a blueprint of how plugins are loaded and meant to be updated. Using “start” plugins more fits the workflow like “manually install and forget about it” which is not quite “add to init.lua and forget about it”. Since all plugins are assumed to be listed in the config and are loaded with vim.pack.add, there is functionally no difference between “opt” and “start” plugin types.

Only Git repos can be managed (installed, updated, deleted) by vim.pack. For other ways of plugin distribution, it is suggested to manually download them into a separate, dedicated plugin package (either directly or via symlinked directory). This also includes so called “local” plugins, which users already have on the disk and want to manage themselves.

Plugins installed by vim.pack are expected to be managed/altered only by vim.pack. Which also includes to not update/delete their code by hand. There are safeguards to handle this graciously, but in general there can be problems. To contribute to a plugin you use via vim.pack, the safest approach is to:

If not already, set up a directory for “local” plugins that fits into plugin package structure. The easiest approach is a dedicated package like ~/.local/share/nvim/site/pack/mine/opt or ~/.config/nvim/pack/mine/opt (while adding pack/ directory to .gitignore). It can also be anywhere on the disk but with a symlink to an “opt” part of a known plugin package.
Download it (usually by forking it on a Git forge and using git clone) into a directory for “local” plugins. Use a directory name that is different from the reference plugin (otherwise there would be name conflicts).
Comment out vim.pack.add for the reference plugin in the config and replace it with vim.cmd.packadd('my-local-copy').
Use a local copy for however long you need (make changes, push/pull branches, etc.). When done, revert changes from the previous step to start using reference plugin again.

Well, technically …

… it is possible to update by hand a plugin directly installed by vim.pack. Locate it in core plugin package and start making changes (create branches and commits, push/pull to remotes, etc.). Just make sure to:

Not update the plugin with vim.pack. It will change the state to where its version points, so local changes will not have effect.
Do not cause any big structural changes. For example, it should still be a Git repository and located at the exact path it was before.
Ignore any messages that this plugin is not at a state that vim.pack expects it to be.
Eventually switch back to managing by vim.pack with vim.pack.update({ 'plugin-name' }, { offline = true }).

One more time: this is definitely a “not officially supported, do on your own risk” kind of territory.

A subtle but one of the key things to understand is that vim.pack.add() is just a function. It takes plugin specifications and acts on them immediately. After execution is done without errors, all listed plugins should be available in the current Neovim session.

Some consequences of this design are:

It results into a more unified config: adding a plugin is similar to creating a mapping or an autocommand.
It can be called multiple times with different plugin lists (with minor caveats) for a more “modular” config.
Lazy loading in principle is just “call this exact function, just some time later”.
It can be used interactively like :lua vim.pack.add({ 'https://github.com/nvim-mini/mini.nvim' }).

By default loading plugin is done by executing :packadd (possibly with !) command, which essentially makes plugin’s runtime files known to Neovim and sources some of them (plugin/ and ftdetect/ scripts).

With vim.pack.add() it is also possible to have custom loading logic. This can be useful to do something more or do nothing at all. The latter is useful as a workaround for some complex lazy loading. For example:

1vim.pack.add({
  'https://github.com/neovim/nvim-lspconfig',
2}, { load = function() end })

1: “Register” plugin, but not load it right away
2: Do nothing instead of :packadd to load

Specification

Each plugin can be specified as a single string describing its source, i.e. from where to download its files (git clone for install and git fetch to update). Please use this approach if no extra tweaking is required.

By default the plugin will be installed as source’s repository name and will get updates following default branch (usually main or master). It is also possible to tweak this by specifying table specification instead of a single source string. Like this:

vim.pack.add({
1  { src = 'https://github.com/nvim-mini/mini.nvim', version = 'stable' },
2  { src = 'https://github.com/neovim/nvim-lspconfig', name = 'lspconfig' },
3  'https://github.com/nvim-treesitter/nvim-treesitter',
})

1: Use updates from stable Git reference (branch, tag, or commit)
2: Use custom name
3: Table and string specifications can be mixed

To follow semver-like named tags, use :h vim.version.range() as version:

vim.pack.add({
  {
    src = 'https://github.com/nvim-mini/mini.nvim',
1    version = vim.version.range('*')
  },
  {
    src = 'https://github.com/neovim/nvim-lspconfig',
2    version = vim.version.range('2.x')
  },
})

1: Always try installing latest semver tag
2: Install latest semver tag if it is >=2.0.0 and <3.0.0

Use data field to store/pass extra information or plugin specific methods:

local selective_load = function(plug_data)
1  if (plug_data.spec.data or {}).skip_load then return end
  vim.cmd.packadd(plug_data.spec.name)
end

vim.pack.add({
  'https://github.com/nvim-mini/mini.nvim',
  { src = 'https://github.com/neovim/nvim-lspconfig', data = { skip_load = true } },
}, { load = selective_load })

1: Do not load if explicitly asked

Lockfile

On top of listing used plugins in a config (to control how they are loaded), vim.pack stores extra information in its lockfile: nvim-pack-lock.json in user’s config directory. It contains JSON encoded information about the current state of all plugins managed by vim.pack. It is meant to be treated like a part of the config (like tracked via version control, for example) but should not be modified by hand.

The lockfile serves several purposes:

It is used as a “latest working state” reference when bootstrapping the config on the new machine. In this case during the very first vim.pack.add() call all plugins that are present in the lockfile but absent on disk are installed all at once.
As a consequence of the previous point, it makes it possible to ensure that even lazy loaded plugins are installed right away at the expected state and not when their first vim.pack.added.
It enables easier “revert the latest update” workflow by reverting the lockfile and updating to the lockfile’s state.
It contains information about plugin’s version, i.e. target state when updating. This is useful when updating if there are not-yet-active plugins (since there is no vim.pack.add() call yet to say which version it follows).
In future it will allow to store more information about plugins to perform more actions without much startup overhead. Like provide information about minimum expected Neovim version (per plugin) or plugin dependencies (to at least ensure that they are already loaded).

If something is done to plugins not via vim.pack methods, lockfile can become out of sync with what is present on disk. Following troubleshooting steps should usually help.

Hooks

A common requirement for managing plugins is to be able to perform dedicated actions (usually called “plugin hooks”) whenever plugin’s state changes. Like “build/compile the plugin”, “update parsers installed by this plugin”, “perform initial registration”.

The suggested interface for that is by creating autocommand(s) for dedicated vim.pack events: PackChangedPre (before the change) and PackChanged (after the change). These events are triggered whenever plugins are affected via vim.pack functions.

Autocommands for these events will receive information about affected plugin via event data. It will contain at least plugin’s name and specification, whether it is active, and what kind of change it is. There are three major kinds of changes:

kind=install - initial plugin install, before loading.
kind=update - update already installed plugin, possibly not loaded.
kind=delete - delete from disk.

Here is an example of updating tree-sitter parsers whenever plugin named ‘nvim-treesitter’ is updated:

vim.api.nvim_create_autocmd('PackChanged', { callback = function(ev)
  local name, kind = ev.data.spec.name, ev.data.kind
1  if name == 'nvim-treesitter' and kind == 'update' then
2    if not ev.data.active then vim.cmd.packadd('nvim-treesitter') end
    vim.cmd('TSUpdate')
  end
end })

1: Update tree-sitter parsers whenever ‘nvim-treesitter’ updates
2: Make sure that ‘nvim-treesitter’ is loaded to use :TSUpdate

The long-term plan is to move defining common hooks (like “after install” and “after update”) from user’s responsibility to plugin’s. One approach is to use some sort of standardized file in plugin root that tells plugin manager what scripts to execute on certain events. This is commonly mentioned as “add packspec support”. This should remove the need for custom hooks for most users.

Note

One important caveat worth mentioning is about plugin install hooks. For them to work, their autocommand has to be created before the vim.pack.add() call that does the installation. Otherwise Neovim can’t know about that hook (at least before there is a packspec support).

Depending on the level of robustness you want to achieve for your config, there are several degrees of handling this:

Create an autocommand before vim.pack.add() that lists the plugin. This will run the hook when the plugin is installed for the very first time.
(Recommended) Create an autocommand before the very first vim.pack.add(). This will run the hook even when installing the plugin based on the lockfile.
If the hook absolutely needs to have plugin’s data (like if it contains project build instructions), the plugin should be listed in the very first vim.pack.add(). If this plugin is intended to be lazy loaded, register it without loading and use vim.cmd.packadd when later loading.

Config organization

Single `vim.pack.add()`

This is the most robust approach around which vim.pack was designed. Have a single vim.pack.add() that installs+loads plugins and (if needed) create one autocommand for hooks prior to it. Also works well when “bootstrapping” config on new machine (since it automatically resolves possible installation hooks problems).

Here is an example:

init.lua

1vim.api.nvim_create_autocmd('PackChanged', { callback = function(ev)
  local name, kind = ev.data.spec.name, ev.data.kind
  if name == 'nvim-treesitter' and kind == 'update' then
    if not ev.data.active then vim.cmd.packadd('nvim-treesitter') end
    vim.cmd('TSUpdate')
  end
end })

2vim.pack.add({
  'https://github.com/nvim-mini/mini.nvim',
  'https://github.com/neovim/nvim-lspconfig',
  'https://github.com/nvim-treesitter/nvim-treesitter',
})

3vim.cmd.colorscheme('miniwinter')
require('mini.basics').setup()
require('mini.surround').setup()
vim.lsp.enable({ 'lua_ls' })

1: Define hooks via autocommand(s)
2: Add (maybe install and load) all at once
3: Use plugins immediately

It should be enough for most users. The two most common downsides expressed about this approach are:

It is not “modular” enough as many people prefer spreading plugin configuration across multiple files. The usual answer is to use many vim.pack.add() calls.
It loads all plugins immediately during startup which can visibly affect startup time. It also increases ‘runtimepath’ (which can have slightly negative impact). The answer is to use lazy loading, but please only to a moderate extent. Extreme lazy loading usually comes with a hidden cognitive overhead both when using and maintaining the config.

Many `vim.pack.add()`

Usually very similar to a “single vim.pack.add()” approach but with many vim.pack.add calls spread across single or multiple files.

One way to do it is to add files inside plugin/ directory of the config. This way they will be discovered and executed (in alphabetical order) automatically during startup.

Here is an example:

plugin/mini.lua

vim.pack.add({ 'https://github.com/nvim-mini/mini.nvim' })
vim.cmd.colorscheme('miniwinter')
require('mini.basics').setup()
require('mini.surround').setup()

plugin/nvim-lspconfig.lua

vim.pack.add({ 'https://github.com/neovim/nvim-lspconfig' })
vim.lsp.enable({ 'lua_ls' })

plugin/nvim-treesitter.lua

vim.api.nvim_create_autocmd('PackChanged', { callback = function(ev)
  local name, kind = ev.data.spec.name, ev.data.kind
  if name == 'nvim-treesitter' and kind == 'update' then
    if not ev.data.active then vim.cmd.packadd('nvim-treesitter') end
    vim.cmd('TSUpdate')
  end
end })
vim.pack.add({ 'https://github.com/nvim-treesitter/nvim-treesitter' })

Note

In general it should be fine to use vim.pack.add for the same plugin several times in different places. This can come up when some plugin is used as a dependency for several other plugins. The first call will load the plugin while all the next ones will be ignored (vim.pack.add() will do nothing for active plugin).

However, for clearer config I would suggest to have only a single vim.pack.add per plugin. Just make sure that it is executed before plugins that depend on it. In case of a plugin/ directory, automated sourcing is alphabetical, so adjusting the file name should work here.

Note

The current single fragility of this approach occurs when “bootstrapping” from the lockfile a plugin that requires an action during install. See dedicated note about possible solutions.

In this particular example a solution could be to create all installation hooks in ‘init.lua’ file:

init.lua

vim.api.nvim_create_autocmd('PackChanged', { callback = function(ev)
  -- Various installation hooks
end})

Lazy loading

One of the ways for users to improve startup and runtime performance, is to delay loading a plugin, a.k.a. “lazy load” it. Ideally, there should not be a need for that to improve startup time: a plugin should do negligible amount of work when setting itself up. However, different people perceive time differently and use different machines, so it still is something that should be possible.

Functionally, there are two types of plugin lazy loading:

“Load not during startup” - improves startup time until first draw at the cost of still loading all plugins (might slightly affect runtime performance). It is an approach that is easy to understand and maintain, though.
“Load just before it is needed” - improves overall performance at the cost of a more complex config.

Please be careful when deciding which plugins to lazy load. Some functionality needs to be available during startup before first redraw: colorscheme, statusline/tabline, starter dashboard, etc.

The vim.pack is designed with lazy loading in mind, but definitely not as a front and center use case. Use it moderately.

The basic idea is to call vim.pack.add() not during startup but register it to be called whenever you want to load the plugin.

The “load not during startup” approach can be done via vim.schedule():

init.lua

vim.schedule(function()
  vim.pack.add({
1    'https://github.com/nvim-mini/mini.cmdline',
    'https://github.com/nvim-mini/mini.completion',
  })
end)

1: Use standalone ‘mini.nvim’ repos for vim.pack.add() demonstration purposes

The “load just before it is needed” approach can become complex if taken at face value. My personal suggestion is to only use basic autocommands and not rely on any complex logic (like “load on mapping”, etc.).

Here is an example:

init.lua

1vim.api.nvim_create_autocmd('CmdlineEnter', { once = true, callback = function()
  vim.pack.add({ 'https://github.com/nvim-mini/mini.cmdline' })
2  require('mini.cmdline').setup()
end })

3vim.api.nvim_create_autocmd('InsertEnter', { once = true, callback = function()
  vim.pack.add({ 'https://github.com/nvim-mini/mini.completion' })
  require('mini.completion').setup()
end })

1: Load once when entering Command-line mode
2: Explicitly set up ‘mini.nvim’ module
3: Load once when entering Insert mode

Both of these approaches can be unified and improved by using a dedicated safely() wrapper from ‘mini.misc’ module of ‘mini.nvim’. With this, the config is more robust (errors will be reported as warnings to not block code execution and load all plugins) and unified:

1vim.pack.add({ 'https://github.com/nvim-mini/mini.misc' })
local misc = require('mini.misc')
local later = function(f) misc.safely('later', f) end
local on_event = function(ev, f) misc.safely('event:' .. ev, f) end

2later(function()
  vim.pack.add({ 'https://github.com/nvim-mini/mini.cmdline' })
3  require('mini.cmdline').setup()
end)

4on_event('InsertEnter', function()
  vim.pack.add({ 'https://github.com/nvim-mini/mini.completion' })
  require('mini.completion').setup()
end)

1: Use standalone ‘mini.nvim’ repos for vim.pack.add() demonstration purposes
2: Load some time later after startup
3: Explicitly set up ‘mini.nvim’ module
4: Load when entering Insert mode

Note

When adding a new lazy loaded plugin, make sure it is installed. Either trigger its loading in a new session or manually run vim.pack.add() with its source.
This also has the same “install hooks” fragility as the many vim.pack.add() approach with the same solutions.

Update

Updating already installed plugins is done via vim.pack.update(). There is no dedicated user command yet.

Executing :lua vim.pack.update() (without arguments) will update all plugins and :lua vim.pack.update({ 'mini.nvim' }) will update selected installed plugins specified by their name. It means:

Download new changes from plugin sources.
Compute new target revision and all the changes (git log) between current and target revisions.
By default show a new tabpage with information about the update. This is known as a confirmation buffer. To skip the confirmation step, apply all pending updates immediately by setting force = true option of vim.pack.update().

Every update that was actually done is recorded in a dedicated nvim-pack.log file inside “log” standard path.

The goal of the confirmation buffer is to show update details for the user to read, confirm (execute :write for that) or deny (close the window for that, like with :quit) the update. Here is an example of how it looks:

There are several buffer-local nice things to improve user experience:

The ]] and [[ mappings navigate through plugin sections forwards and backwards.
There is a so-called “in-process” (i.e. created in Neovim session with Neovim’s Lua code) LSP server enabled specifically in confirmation buffer. It provides several features in an LSP compatible way. This means that they will work both with default LSP mappings and with any custom mappings.

The supported LSP methods are:
- ‘textDocument/documentSymbol’ to show structure of the buffer. By default opens a location list, but will work with, for example, any picker providing LSP document symbols picker.
- ‘textDocument/hover’ - show more information at cursor, like details of a particular pending change or newer tag. By default opens a floating window showing the change; execute the hover action again to jump into the window or move cursor for the window to disappear.
- ‘textDocument/codeAction’ - show code actions relevant for a “plugin at cursor”. Like “delete” (if plugin is not active; useful if you only removed plugin from config but did not delete it), “update” or “skip updating” (if there are pending updates).

Other common ways to use vim.pack.update():

:lua vim.pack.update(nil, { force = true }) - force updates immediately without confirmation buffer. Useful when scripting.
:lua vim.pack.update(nil, { offline = true }) - show the current state of plugins without downloading new changes from sources. Useful to interactively explore installed plugins.
:lua vim.pack.update(nil, { target = 'lockfile' }) - make sure that plugin state on disk is the same as recorded in the lockfile. Useful for reverting updates: ensure the lockfile is as it was before the update and execute the command.

Delete

Deleting a plugin is a relatively straightforward two step process:

Remove from the config any logic for loading the plugin. Otherwise it will be reinstalled on the next startup.
Use vim.pack.del() to delete plugin(s) from disk. This will also remove the plugin from the lockfile. Here is an example: :lua vim.pack.del({ 'nvim-lspconfig', 'nvim-treesitter' }).

Do not delete directory with plugin code by hand. This will not adjust lockfile, which means the plugin will be reinstalled on the next startup.

Troubleshoot

To err is human. When you feel there might be problems with vim.pack, run :checkhealth for it. Like this: :checkhealth vim.pack.

It should report any known/common issues together with best-effort suggestions on how to fix it. For example it will:

Detect missing or problematic lockfile entry.
Whether lockfile is not aligned with what is on the disk.
Notify if there are not active (installed but not loaded) plugins. Which might be a sign that it was removed from the config but not fully deleted.

Migrate

There is a chance that you already use a plugin manager, in which case in order to use vim.pack you’d have to migrate from the previous one. And my personal suggestion would be to do it. It usually results in a simple and more “native” config than alternatives while still being enough to comfortably daily drive. It is also built-in, which means that it 1) has dedicated and knowledgeable people maintaining it; and 2) has basically the same stability guarantees as the Neovim core itself. The downside might be a slower release cycle than a regular plugin, so you’d have to wait longer for possible fixes and new features (or use Nightly releases).

Depending on the config complexity and the number of used plugins, it might be a tedious task. But in a nutshell:

Update the config to use vim.pack instead of the previous plugin manager. Make sure that there is no use of the previous plugin manager whatsoever (otherwise it will become confusing to locate problems).
Make sure that plugins and accompanying files from the previous plugin manager are not on disk. This might be crucial to not have the same plugin installed in different places.

For this, find the location of where the plugin manager installed plugins and delete the directory manually.

Here are a couple of approaches that could make the transition easier:

Instead of changing the “main” config, adjust a temporary one (see :h $NVIM_APPNAME) at your own pace without the pressure of not having the fully working setup. You can start either with a full copy of the “main” config or start fresh.

For example, create ~/.config/nvim-vim-pack directory. Either empty to start fresh or by copying ~/.config/nvim. Adjusting nvim-vim-pack config will have no impact on the “main” nvim config. Use NVIM_APPNAME=nvim-vim-pack nvim to start Neovim with the nvim-vim-pack config. When you feel ready, move the content back to ~/.config/nvim (it will reinstall vim.pack plugins into a permanent “data” standard path).
Start with a simple one vim.pack.add() style of config and see if it fits your needs. It might be surprising and refreshing to trade the startup speed for config simplicity.

If it doesn’t feel right, you can start modularizing the config. And only if absolutely needed, try lazy loading some plugins.

mini.deps

The ‘mini.deps’ was initially designed with the idea of being merged as Neovim’s built-in plugin manager. The overall concept proved to be rather successful and after about 1.5 years of public testing it was used as a basis for vim.pack.

In many ways, vim.pack is a better and slicker version of ‘mini.deps’ which is why it will eventually be recommended instead of ‘mini.deps’. So the migration should be rather painless. But here are a couple of pointers:

Instead of MiniDeps.add('user/repo') use vim.pack.add({ 'https://github.com/user/repo' }), i.e. use full URL and a list instead of a single string.
In table specification: source -> src, checkout -> version.
Resolve dependencies manually by listing them in vim.pack.add() list before target plugin. It shouldn’t be a problem to vim.pack.add() the same plugin several times, but it is better to resolve to the point of every plugin being added exactly once.
Rewrite hooks to be in autocommand form.
Instead of MiniDeps.now() and MiniDeps.later(), use MiniMisc.safely().
Do not forget to remove plugins (located in site/pack/deps subdirectory of “data” standard path) and possible mini-deps-snap snapshot file. Otherwise there will be conflicts (since ‘mini.deps’ also uses plugin package approach).

You can see an example of a real config migration in MiniMax: the main theme of moving from nvim-0.11 to nvim-0.12 reference config is changing a plugin manager from ‘mini.deps’ to vim.pack.

Here is a simpler example:

‘mini.deps’ config (excluding the part of bootstrapping ‘mini.nvim’ or ‘mini.deps’):

MiniDeps.add('nvim-mini/mini.nvim')
require('mini.basics').setup()

MiniDeps.add({
  source = 'nvim-treesitter/nvim-treesitter',
  checkout = 'main',
  hooks = { post_checkout = function() vim.cmd('TSUpdate') end },
})

The translated vim.pack config:

vim.pack.add({ 'https://github.com/nvim-mini/mini.nvim' })
require('mini.basics').setup()

vim.api.nvim_create_autocmd('PackChanged', { callback = function(ev)
  local name, kind = ev.data.spec.name, ev.data.kind
  if name == 'nvim-treesitter' and kind == 'update' then
    if not ev.data.active then vim.cmd.packadd('nvim-treesitter') end
    vim.cmd('TSUpdate')
  end
end })

vim.pack.add({
  {
    src = 'https://github.com/nvim-treesitter/nvim-treesitter',
    version = 'main'
  },
})

lazy.nvim

The folke/lazy.nvim is the most used plugin manager at the time of this writing. And rightly so: it is very capable with lots of features. Ironically, this itself makes it not very suitable to be a part of Neovim as most of the features come with significant code and maintenance complexity. Plus the whole idea of treating lazy loading as the main goal of a plugin manager does not sit well with Neovim core team.

By design, not all ‘lazy.nvim’ capabilities are one-to-one reproducible in vim.pack. My best suggestion would be to follow both approaches suggested earlier: use temporary config and start with simple approach first to see that maybe there is nothing much to miss from ‘lazy.nvim’.

Couple of pointers:

Use full URL as a source (as string or src field) and a single version instead of branch / tag / commit / version / pin fields.
Instead of the opts field use a dedicated way to configure a plugin (should be mentioned in plugin’s documentation/README) after vim.pack.adding it. Typically it is something like require('plugin').setup(opts), which ‘lazy.nvim’ does behind the scenes (but not vim.pack.add()).
There is no built-in lazy loading with vim.pack, so specification fields like cmd, event, ft, keys can not be translated directly. For emulating loading on event see “Lazy loading” section.
The directory where ‘lazy.nvim’ stores its plugins is lazy subdirectory of “data” standard path. Delete it manually before migrating.
If you use LazyVim, then it is probably a better idea to start from a clean config and build from there. As LazyVim is heavily based on using ‘lazy.nvim’ as its plugin manager.

As for a startup speed, when comparing simple configs of vim.pack and ‘lazy.nvim’, the latter will most certainly have faster results. Primarily because it is built around the concept of “lazy load and fast custom load whenever you can”. How much faster - depends on the number of plugins.

However, there are ways of making config with vim.pack have faster startup:

The most speedup usually comes from lazy loading, at the cost of extra a more complex config. Choosing the right balance between the two is up to you.
For not lazy loaded parts, not trivial amount of improvement can come from adding vim.loader.enable() call as the first line in ‘init.lua’. It implements some dark “fast load” magic that was blessed by Folke himself. After a few restarts it usually improves startup, especially if there are a lot of require() calls.

How big the result will be is hard to tell, as it depends on variety of things. In real world configs without much lazy loading just this one line can speed up as high as ~30% (I’ve seen examples of 137ms->99ms and 430ms->315ms improvement), maybe more.

From experience, implementing both of these approaches can result in a startup at least on par with ‘lazy.nvim’, if not better. My personal choice of startup optimization is to use only a handful of plugins (less things to load) together with a very simple lazy loading (MiniMax style); no vim.loader.enable() (as startup time is small enough: ~38ms compared to ~34ms with it).

The most recommended way of setting up ‘lazy.nvim’ plugins seems to be a so called “structuring plugins” approach. Beware that those lua/plugins/ plugin files are discovered and sourced by ‘lazy.nvim’ automatically. Just translating each file to use vim.pack.add() will not be enough, make sure to source those files during startup. One approach that I can recommend is to move them from lua/plugins/ to plugin/ directory (notice the singular case). The plugin/ runtime files are sourced automatically during startup by Neovim itself.

Here is an example:

‘lazy.nvim’ “structured” config:

init.lua

-- Bootstrap lazy.nvim
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
-- ...

-- Setup lazy.nvim
require("lazy").setup({
  spec = {
    { import = "plugins" },
  },
})

lua/plugins/mini-hues.lua

return {
  'nvim-mini/mini.hues',
  lazy = false,
  priority = 1000,
  config = function()
    vim.cmd.colorscheme('miniwinter')
  end,
}

lua/plugins/mini-completion.lua

return {
  'nvim-mini/mini.completion',
  event = 'InsertEnter',
  dependencies = { 'nvim-mini/mini.snippets' },
  config = function()
    require('mini.snippets').setup()
    require('mini.completion').setup()
  end,
}

lua/plugins/mini-pairs.lua

return {
  'nvim-mini/mini.pairs',
  opts = {
    modes = { command = true },
  },
}

The translated vim.pack config (notice directory change lua/plugins -> plugin and 00-mini-hues.lua to force load it first):

init.lua

-- No special setup if 'plugin/' directory is used

plugin/00-mini-hues.lua

vim.pack.add({ 'https://github.com/nvim-mini/mini.hues' })
vim.cmd.colorscheme('miniwinter')

plugin/mini-completion.lua

vim.api.nvim_create_autocmd('InsertEnter', {
  once = true,
  callback = function()
    vim.pack.add({
      'https://github.com/nvim-mini/mini.snippets',
      'https://github.com/nvim-mini/mini.completion',
    })
    require('mini.snippets').setup()
    require('mini.completion').setup()
  end,
})

plugin/mini-pairs.lua

vim.pack.add({ 'https://github.com/nvim-mini/mini.pairs' })
require('mini.pairs').setup({
  modes = { command = true },
})

How many Neovim plugins is too many

Evgeni Chasnovski — Tue, 27 Jan 2026 00:00:00 GMT

First, to directly answer the implied question in the title: there is no specific number. Each Neovim user decides for themselves how many plugins bring the most joy out of using the editor. It can be as low as zero and as many as 100+.

What I am curious about is how the number of loaded plugins affects overall performance of using Neovim.

Motivation

There are at least two main reasons for me to explore this:

Measure a performance benefit of using ‘mini.nvim’ as a single plugin instead of many its standalone repos.
Get an actual data about whether lazy loading can be objectively justified from at least performance point of view.

I know there should be a performance difference in both cases since loading a plugin adds a path entry in Neovim’s runtime. This is a way to make Neovim “know” about available plugin code/data and use it whenever needed. Like when:

Doing require('module-name') the first time for ‘module-name’ yields searching through all known ‘lua/’ runtime directories.
Assigning filetype to a buffer (which is a fairly frequent action) yields searching through ‘ftplugin/’ runtime directories to load filetype plugin script(s).

I don’t have an accurate estimation of how frequent this happens. Especially since it highly depends on which plugins are used (as they tend to set filetype for their internal buffers). But my quick testing on Neovim>=0.12 with vim._core.ui2 enabled hints that it can be in the vicinity of 500 per active Neovim usage session.
Attaching an LSP client on Neovim>=0.11 yields searching through ‘lsp/’ runtime directories.
And so on. More information is in above link about Neovim’s runtime, plus :h :runtime and :h runtime-search-path

Benchmark

The only way to answer these questions is by designing and performing benchmarks. Here I’ll describe the necessary basics of what was done, but you can find exact scripts and possibly more details here.

There are reasonably two performance aspects to benchmark: startup and runtime (i.e. everything after startup).

The main effect of loading plugins on startup performance is due to increasing ‘runtimepath’ value and immediately using it during startup. The two most common example here are: execute require('plugin-name') (like when using its method to enable and/or configure the plugin) and Neovim’s automatic sourcing of ‘plugin/’ files.

The main effect on runtime performance should be just increased ‘runtimepath’. So this is not quite plugin number specific, but installing plugins is the main way to increase the number of runtime paths.

With that in mind, I settled on the following benchmarking approach:

One benchmark is done for a combination of a number of loaded plugins (n_plugins) and the way they are loaded (config_type).
Procedurally generate each plugin so that it has rudimentary but plausible ‘lua/’ and ‘plugin/’ code. See “Plugin code”.
Procedurally generate several config types describing how plugins are loaded via vim.pack (available on Neovim>=0.12). The whole config is basically a single ‘init.lua’ file. See “Config types”.
Run the Neovim with the config once to install necessary plugins.
Measure startup by doing the equivalent of nvim --startuptime file-{config_type}-{n_plugins} 10 times to later average out. From startup log file extract:
- How long did it take to source ‘init.lua’.
- How long did it take to source all ‘plugin/’ files.
- Overall startup time.
Once per benchmarked config_type+n_plugins combo set filetype and measure time it took. Repeat many times with each try for a fresh buffer and for a filetype that doesn’t have filetype scripts (to not include their source time in benchmarks). Take a median time as a benchmark result. I settled on 1001 times per each combo, which should be enough to get stable sub millisecond precision.
Tested loaded plugin numbers: 0, 5, 10, …, and 50 loaded plugins. Include zero for a sanity check and to get a reference for a total startup time.

Note

Benchmarks were done at the time when Neovim 0.12 is still in development. The AppImage with the following version was used:

NVIM v0.12.0-dev-2435+g18c5f06c9f
Build type: RelWithDebInfo
LuaJIT 2.1.1771967821

Plugin code

Each plugin has a very simple placeholder functionality and is written with “good practices” in mind. In particular, plugin number NN (which is a number from 01 to n_plugins, the total number of loaded plugins) contains:

lua/pluginNN.lua

local run = function() _G.value = "PluginNN" end
local config = function() _G.pluginNN = { "PluginNN" } end
return { config = config, run = run }

plugin/pluginNN.lua

vim.api.nvim_create_user_command("PluginNN", function() require("pluginNN").run() end, {})
vim.keymap.set("n", "(PluginNN)", function() require("pluginNN").run() end)

It is generated inside ‘host/’ subdirectory of current working directory and installed using file:///path/to/working/directory/host/pluginXX as a source.

Config types

Three types of configs are benchmarked:

Grouped add() - many independent plugins are installed and loaded as a group in a single vim.pack.add() call and later configured. This is the most robust and straightforward way to install many plugins with vim.pack.

init.lua

vim.pack.add({
  'file:///path/to/working/directory/host/plugin01',
  -- ...
  'file:///path/to/working/directory/host/pluginXX',
}, { confirm = false })

require('plugin01').config()
-- ...
require('pluginXX').config()

Separate add() - many independent plugins are installed, loaded, and configured in “sequential” manner. This installs and loads one plugin at a time while immediately configuring it. This is meant to check if having plugin entry in ‘runtimepath’ closer to its start (since :packadd from vim.pack.add() adds an entry very close to the start) adds a meaningful startup improvement (as require('pluginNN') then needs to traverse fewer directories). SPOILER: it’s complicated.
```
init.lua
```
```
vim.pack.add({ 'file:///path/to/working/directory/host/plugin01' }, { confirm = false })
require('plugin01').config()

-- ...

vim.pack.add({ 'file:///path/to/working/directory/host/pluginXX' }, { confirm = false })
require('pluginXX').config()
```

Single plugin - single plugin that combines all Lua modules and plugin files of separate plugins into one. All ‘lua/pluginNN.lua’ and ‘plugin/pluginNN.lua’ files are combined under a single directory. This provides the same functionality as many plugins, but “packaged” in a single plugin. Similar to how ‘mini.nvim’ is related to its standalone repos. This only adds a single entry to ‘runtimepath’ and is also used as a reference to compare against.
```
init.lua
```
```
vim.pack.add({ 'file:///path/to/working/directory/host/singleXX' }, { confirm = false })

require('plugin01').config()
-- ...
require('pluginXX').config()
```

Note

All config types use vim.pack.add() to install and load plugins. For installed plugins it essentially executes :packadd! during startup, so modifies ‘runtimepath’ immediately. Other plugin managers can and do behave differently while requiring more elaborate ways of delayed execution of require('pluginNN').config().

Prior expectations

Results for 0 loaded plugins do not depend on config type. Nothing loaded in various ways is still nothing loaded. Can be used for a sanity check and reference for total startup time.
Startup time is the best for Single plugin config type, followed by Separate vim.pack.add(), followed by Grouped vim.pack.add().
Both “many plugins” approaches visibly grow with the number of plugins.
Runtime performance behaves the same for both “many plugins” config types and is visibly worse than for “single plugin”.

Results

Edit on 2026-02-27: initial version of this post was done on v0.12.0-dev-2101+gd93e150888 development version of Neovim. Some observations didn’t feel right, which resulted into me suggesting an optimization upstream. It was promptly addressed by Neovim wizard @bfredl (the quick turnaround is mostly because it affects the vim.pack in the upcoming Neovim 0.12 release). Each section has “Initial results” spoiler preserved for posterity.

Startup

Here are the results of benchmarking startup time (semi transparent points are actual times, line and text represent median times).

Observations:

Having zero plugins indeed adds nothing to startup time.
Best performance is indeed for Single plugin. Having constant number of ‘runtimepath’ entries can save up to 50% of startup time for 50 plugins.
However, Separate add() is not visibly faster than Grouped add(). This probably has to do with the fact that ‘runtimepath’ option has special treatment: it is internally smartly cached on every :packadd to increase startup performance.
Sourcing ‘plugin/’ does not depend on config type and grows close to linearly with the number of loaded plugins. The exact numbers are rather small, though.
Total startup time is mostly affected by ‘init.lua’.

Initial results

Separate add() is much slower than Grouped add(). At first, I thought that this is a result of constant overhead of a vim.pack.add call, but similar results can be seen with vim.cmd('packadd! pluginXX').

After digging through the Neovim code base (with the help of Luis Calle), the reason seems to be internal caching. In particular:
- Searching in require() is done by a custom package loader that uses private vim.api.nvim__get_runtime().
- The private vim.api.nvim__get_runtime() uses a helper that does some caching of runtime files if ‘runtimepath’ has changed.
So instead of the expected “Add to ‘runtimepath’” -> “require searches small number of directories”, there is a “Do some ‘runtimepath’ caching” step in the middle. It seems to have been added with caching pack/*/start/* plugins in mind.

Although quick, it still adds a significant overhead at this millisecond scale of actions. But on the other hand, this approach allows to have more “separated” config structure, which many people like.
There is an overall and uniform ~10% improvement in startup speed between initial and “new” results. This might be a result of another startup improvement done within a month between benchmarks, since the startup time with zero plugins has improved by the same amount.

However, since there is a similar improvement in “Runtime” results, it might be due to how the benchmarking machine was feeling on a particular day.

Runtime

Observations:

Indeed for both “many plugins” config types runtime performance is the same.
Switching to a single plugin can drastically reduce runtime overhead complexity from nearly linear to nearly constant.

Initial results

Conclusion

Loading plugins indeed adds a measurable performance overhead. Both during startup and runtime.
Reducing the number of loaded plugins (be it by using a single “bundle plugin” or by lazy loading plugins some time later) can measurably improve performance. The saved time grows linearly with the number of reduced plugins and can be as high as 50% of startup/runtime overhead for 50 reduced plugins.
There is no practical difference between “one vim.pack.add()” (load all necessary plugins at once and later configure in a series of require() calls) and “separate vim.pack.add()” (vim.pack.add() -> require() -> vim.pack.add() -> require()). This seems to have to do with internal caching of ‘runtimepath’ option.
Are these findings useful? I’d say yes. On paper, the amount of saved time is very small: order of tens of milliseconds during startup and one millisecond during runtime.

However, Neovim users take pride in their instantaneous startup and runtime performance. When looking at a big picture of a general advice for users, the value of saved time (number of opening Neovim x 10 ms + number of runtime searching per session x 1 ms ~ 5 x 10 + 500 x 1 = 550 ms per day) can be visible if multiplied by the number of users and number of passed days.
My personal (very biased) recommendation would be this: if you want to optimize startup and runtime performance benchmarked here, switching from many separate plugins to one plugin that provides same/similar functionality is the best course of action here. If that is not possible, then consider doing some simple lazy loading (like after first screen draw or on InsertEnter/CmdlineEnter events).

It is also completely fine to not care about millisecond level overhead in favor of using plugins and structure that brings you more joy. In the end, the choice is always up to the user.

Neovim now has built-in plugin manager

Evgeni Chasnovski — Fri, 04 Jul 2025 00:00:00 GMT

Color scheme	Stargazers
folke/tokyonight.nvim	3476 stars
catppuccin/nvim	2639 stars
rebelot/kanagawa.nvim	2219 stars
EdenEast/nightfox.nvim	2055 stars
projekt0n/github-nvim-theme	1379 stars

Color scheme PR	Language	Time to first reaction	Outcome
bluz71/vim-moonfly-colors	Vimscript	~ 1 day	Revised and accepted
bluz71/vim-nightfly-guicolors	Vimscript	~ 1 day	Revised and accepted
catppuccin/nvim	Lua	~ 6 days	Merged
EdenEast/nightfox.nvim	Lua	~ 1 day	Merged
folke/tokyonight.nvim	Lua	> 14 days (no reaction yet)	Open
marko-cerovac/material.nvim	Lua	~ 3 days	Merged
navarasu/onedark.nvim	Lua	~ 1 day	Merged
projekt0n/github-nvim-theme	Lua	~ 1 day	Merged
rebelot/kanagawa.nvim	Lua	~ 7 days	Waiting for approval
sainnhe/edge	Vimscript	~ 1 day	Merged
sainnhe/everforest	Vimscript	~ 1 day	Merged
sainnhe/gruvbox-material	Vimscript	~ 1 day	Merged
sainnhe/sonokai	Vimscript	~ 1 day	Merged
shaunsingh/nord.nvim	Lua	~ 1 day	Merged

Evgeni Chasnovski

A Guide to vim.pack (Neovim built-in plugin manager)

Concepts

Lua

Runtime files

Plugin packages

Install and load

Specification

Lockfile

Hooks

Config organization

Single vim.pack.add()

Many vim.pack.add()

Lazy loading

Update

Delete

Troubleshoot

Migrate

mini.deps

lazy.nvim

How many Neovim plugins is too many

Motivation

Benchmark

Plugin code

Config types

Prior expectations

Results

Startup

Runtime

Conclusion

Neovim now has built-in plugin manager

Neovim + mini.pick + nushell = CLI fuzzy picker. Why? Because why not.

PSA for color scheme authors: you might want to adjust PmenuSel

You can remove padding around Neovim instance with this one simple trick…

Neovim now has built-in commenting

Exactly 10 years ago Neovim had its first commit

Neovim now has its own default color scheme

Floating windows in Neovim can now have footer

Average Neovim color scheme

You don’t need ‘vim-rooter’ (usually) or How to set up smart autochange of current directory

Results of “Neovim built-in options survey”

Neovim built-in options survey needs your contribution

Create and apply randomly generated Base16 color scheme

Usage of ‘after/ftplugin’ directory for filetype-specific configuration

I contributed to (mostly) 14 top-rated Neovim color schemes. Here are some observations

StyLua now supports collapsing simple statements

Useful functions to explore Lua objects

Count bounces in table tennis world record

Prologue

Detecting

Counting

Epilogue

Single `vim.pack.add()`

Many `vim.pack.add()`