lazy.nvim/docs/usage/index.md

5.9 KiB

sidebar_position
6

🚀 Usage

▶️ Startup Sequence

lazy.nvim does NOT use Neovim packages and even disables plugin loading completely (vim.go.loadplugins = false). It takes over the complete startup sequence for more flexibility and better performance.

In practice this means that step 10 of Neovim Initialization is done by Lazy:

  1. All the plugins' init() functions are executed
  2. All plugins with lazy=false are loaded. This includes sourcing /plugin and /ftdetect files. (/after will not be sourced yet)
  3. All files from /plugin and /ftdetect directories in your rtp are sourced (excluding /after)
  4. All /after/plugin files are sourced (this includes /after from plugins)

Files from runtime directories are always sourced in alphabetical order.

🚀 Commands

Plugins are managed with the :Lazy command. Open the help with <?> to see all the key mappings.

You can press <CR> on a plugin to show its details. Most properties can be hovered with <K> to open links, help files, readmes, git commits and git issues.

Lazy can automatically check for updates in the background. This feature can be enabled with config.checker.enabled = true.

Any operation can be started from the UI, with a sub command or an API function:

Command Lua Description
:Lazy build {plugins} require("lazy").build(opts) Rebuild a plugin
:Lazy check [plugins] require("lazy").check(opts?) Check for updates and show the log (git fetch)
:Lazy clean [plugins] require("lazy").clean(opts?) Clean plugins that are no longer needed
:Lazy clear require("lazy").clear() Clear finished tasks
:Lazy debug require("lazy").debug() Show debug information
:Lazy health require("lazy").health() Run :checkhealth lazy
:Lazy help require("lazy").help() Toggle this help page
:Lazy home require("lazy").home() Go back to plugin list
:Lazy install [plugins] require("lazy").install(opts?) Install missing plugins
:Lazy load {plugins} require("lazy").load(opts) Load a plugin that has not been loaded yet. Similar to :packadd. Like :Lazy load foo.nvim. Use :Lazy! load to skip cond checks.
:Lazy log [plugins] require("lazy").log(opts?) Show recent updates
:Lazy profile require("lazy").profile() Show detailed profiling
:Lazy reload {plugins} require("lazy").reload(opts) Reload a plugin (experimental!!)
:Lazy restore [plugins] require("lazy").restore(opts?) Updates all plugins to the state in the lockfile. For a single plugin: restore it to the state in the lockfile or to a given commit under the cursor
:Lazy sync [plugins] require("lazy").sync(opts?) Run install, clean and update
:Lazy update [plugins] require("lazy").update(opts?) Update plugins. This will also update the lockfile

Any command can have a bang to make the command wait till it finished. For example, if you want to sync lazy from the cmdline, you can use:

nvim --headless "+Lazy! sync" +qa

opts is a table with the following key-values:

  • wait: when true, then the call will wait till the operation completed
  • show: when false, the UI will not be shown
  • plugins: a list of plugin names to run the operation on
  • concurrency: limit the number of concurrently running tasks

Stats API (require("lazy").stats()):

{
  -- startuptime in milliseconds till UIEnter
  startuptime = 0,
  -- when true, startuptime is the accurate cputime for the Neovim process. (Linux & macOS)
  -- this is more accurate than `nvim --startuptime`, and as such will be slightly higher
  -- when false, startuptime is calculated based on a delta with a timestamp when lazy started.
  real_cputime = false,
  count = 0, -- total number of plugins
  loaded = 0, -- number of loaded plugins
  ---@type table<string, number>
  times = {},
}

lazy.nvim provides a statusline component that you can use to show the number of pending updates. Make sure to enable config.checker.enabled = true to make this work.

Example of configuring lualine.nvim
require("lualine").setup({
  sections = {
    lualine_x = {
      {
        require("lazy.status").updates,
        cond = require("lazy.status").has_updates,
        color = { fg = "#ff9e64" },
      },
    },
  },
})

📆 User Events

The following user events will be triggered:

  • LazyDone: when lazy has finished starting up and loaded your config
  • LazySync: after running sync
  • LazyInstall: after an install
  • LazyUpdate: after an update
  • LazyClean: after a clean
  • LazyCheck: after checking for updates
  • LazyLog: after running log
  • LazyLoad: after loading a plugin. The data attribute will contain the plugin name.
  • LazySyncPre: before running sync
  • LazyInstallPre: before an install
  • LazyUpdatePre: before an update
  • LazyCleanPre: before a clean
  • LazyCheckPre: before checking for updates
  • LazyLogPre: before running log
  • LazyReload: triggered by change detection after reloading plugin specs
  • VeryLazy: triggered after LazyDone and processing VimEnter auto commands
  • LazyVimStarted: triggered after UIEnter when require("lazy").stats().startuptime has been calculated. Useful to update the startuptime on your dashboard.

Uninstalling

To uninstall lazy.nvim, you need to remove the following files and directories:

  • data: ~/.local/share/nvim/lazy
  • state: ~/.local/state/nvim/lazy
  • lockfile: ~/.config/nvim/lazy-lock.json

Paths can differ if you changed XDG environment variables.