5.9 KiB

Raw Blame History

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:

All the plugins' init() functions are executed
All plugins with lazy=false are loaded. This includes sourcing /plugin and /ftdetect files. (/after will not be sourced yet)
All files from /plugin and /ftdetect directories in your rtp are sourced (excluding /after)
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.

5.9 KiB Raw Blame History