Neovim lazy-nvim¶

ID: lazy
Home page: https://lazy.folke.io
Version requirement: >= 11
Platforms: 🅱️ BSD · 🐧 Linux · 🍎 macOS · ⨂ Unix · 🪟 Windows
Operations: installed · upgrade_all
purl types: pkg:lazy
CLI name: nvim
Every call: nvim --headless <command> -c cquit
Issues and PRs: 📦 manager: vim-based
Source: meta_package_manager/managers/lazy.py

lazy.nvim is a modern plugin manager for Neovim.

lazy.nvim is a Lua plugin, not a standalone binary: each operation below is a Lua one-liner evaluated by a throw-away Neovim process. Plugins are Git clones under stdpath('data')/lazy, pinned by a lazy-lock.json lock file in stdpath('config') that records the exact commit of each one.

Caution

Neovim is the binary mpm executes, and mpm already wraps Neovim’s built-in Vim_Pack, which legitimately keys on the same nvim. The two are told apart by the version probe: it reports a version only when lazy.nvim’s own checkout is found and its version constant reads back, so a host running Neovim without lazy.nvim leaves this manager unavailable instead of shadowing every editor on every machine.

Note

This manager is deliberately limited to inventorying and updating, the two operations lazy.nvim can carry out with nobody at the keyboard. That is already more than the coarse, whole-category upgrade a tool like topgrade performs for the same plugins, since the inventory comes with it.

Caution

No install and no remove: lazy.nvim materializes exactly the plugin set declared in the user’s own Lua configuration. :Lazy install clones what that configuration already names and :Lazy clean drops what it no longer names, so neither takes a plugin of mpm’s choosing. Installing one would mean mpm editing the user’s init.lua, which is configuration mpm does not own. The two operations are therefore not implemented rather than faked, and mpm auto-skips them.

Note

No outdated: :Lazy check does fetch each remote without touching a working tree, but the pending revisions it computes are only readable through a plugin’s private _.updates field, which lazy.nvim documents no contract for. mpm auto-skips the operation and upgrade --all still works.

Documentation: lazy.folke.io.

What `mpm` adds to `lazy`¶

mpm reaches across every manager at once, not lazy alone: mpm installed and mpm outdated cover lazy alongside every other manager you run in one table, mpm upgrade --all updates them together, and mpm sbom exports the whole machine as one bill of materials.

Every mpm command also gains --dry-run and --plan previews, cross-scheme version comparison and purl identifiers. See manager augmentations for how each one is built.

Operations¶

Operation	Supported
`installed`	✓
`outdated`
`orphans`
`search`
`install`
`upgrade`
`upgrade_all`	✓
`remove`
`sync`
`cleanup`
`doctor`

Selecting and configuring `lazy`¶

Deselect lazy for a single run with --no-lazy, or persist the choice in your configuration:

[mpm]
lazy = false

The arguments and environment variables listed in the box atop this page are forced on every lazy call, so runs stay quiet, non-interactive and reproducible: the defaults you would set in CI anyway.

Keep it enabled but tune how mpm drives it with a per-manager override:

[mpm.managers.lazy]
timeout = 900

mpm config-template lazy prints every overridable attribute as a ready-to-paste block.

Recipes¶

A few jobs you would otherwise script around lazy, one mpm command each:

Snapshot and clone a machine: mpm --lazy dump lazy.toml, then mpm restore lazy.toml on the next one.
Export a compliance SBOM: mpm --lazy sbom (CycloneDX by default, --spdx for SPDX).

Privilege escalation¶

mpm runs this manager as the current user and never prepends sudo by default. Flip the policy for its privileged operations with --sudo or the per-manager sudo override.

See privilege escalation for the full policy.

Cooldown¶

State of Neovim lazy-nvim’s release-age gating, from the cooldown support table:

Status: ❌ None

A cooldown only pays off where a compromised release can be withdrawn while the clock runs, and can only be emulated where the registry dates its releases. From the retraction table:

Registry: Upstream Git clones
Retraction: None: a plugin is cloned straight from its upstream repository, so withdrawing a bad revision is its author force-pushing, retagging or deleting it themselves. No index sits in between
Publish date: ❌ a commit or tag date is set by the author and freely rewritable

With --cooldown set, mpm skips this manager’s install and upgrade operations rather than run them unguarded (fail-closed); --allow-unsupported-managers opts back in.

Version probe¶

The version is probed by running:

$ nvim --clean --headless -c lua local p = vim.fn.stdpath("data") .. "/lazy/lazy.nvim" if (vim.uv or vim.loop).fs_stat(p) then vim.opt.rtp:prepend(p) io.write("lazy.nvim " .. require("lazy.core.config").version) end os.exit(0)
lazy.nvim 11.17.5

and extracted with:

r"lazy\.nvim (?P<version>\S+)"

Reference traces¶

Raw native outputs captured in the manager source: the reference mpm’s parsers were written against. If you know Neovim lazy-nvim well and a transcript below looks wrong, or a newer release changed its output format, report it.

$ nvim --headless --clean \
> -c 'lua local f = io.open(vim.fn.stdpath("config") .. "/lazy-lock.json") if f then io.write(f:read("a")) end os.exit(0)' \
> -c 'cquit'
{
  "lazy.nvim": { "branch": "main", "commit": "306a05526ada86a7b30af95c5cc81ffba93fef97" },
  "vim-sensible": { "branch": "master", "commit": "0ce2d843d6f588bb0c8c7eec6449171615dc56d9" },
  "z": { "branch": "master", "commit": "d37a763a6a30e1b32766fecc3b8ffd6127f8a0fd" }
}

Feed any of these through mpm and the raw output becomes one uniform table, the same shape for every manager: filter it, project columns, or export it (mpm --lazy installed --output json, or csv, toml, yaml), each package carrying a purl and a version comparable across managers.

Changelog¶

7.7.0.dev0 (unreleased)
- Add the lazy.nvim Neovim plugin manager with installed and upgrade support. It declares no install or remove: lazy.nvim materializes only the plugin set the user’s own Lua configuration names.