8.3 KiB

Raw Blame History

sidebar_position
6

🚀 Usage

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.

🐛 Debug

See an overview of active lazy-loading handlers and what's in the module cache.

▶️ 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.

📂 Structuring Your Plugins

Some users may want to split their plugin specs in multiple files. Instead of passing a spec table to setup(), you can use a Lua module. The specs from the module and any top-level sub-modules will be merged together in the final spec, so it is not needed to add require calls in your main plugin file to the other files.

The benefits of using this approach:

Simple to add new plugin specs. Just create a new file in your plugins module.
Allows for caching of all your plugin specs. This becomes important if you have a lot of smaller plugin specs.
Spec changes will automatically be reloaded when they're updated, so the :Lazy UI is always up to date.

Example:

~/.config/nvim/init.lua

require("lazy").setup("plugins")

~/.config/nvim/lua/plugins.lua or ~/.config/nvim/lua/plugins/init.lua (this file is optional)

return {
  "folke/neodev.nvim",
  "folke/which-key.nvim",
  { "folke/neoconf.nvim", cmd = "Neoconf" },
}

Any lua file in ~/.config/nvim/lua/plugins/*.lua will be automatically merged in the main plugin spec

For a real-life example, you can check LazyVim and more specifically:

lazyvim.plugins contains all the plugin specs that will be loaded

↩️ Importing Specs, `config` & `opts`

As part of a spec, you can add import statements to import additional plugin modules. Both of the setup() calls are equivalent:

require("lazy").setup("plugins")

-- Same as:
require("lazy").setup({{import = "plugins"}})

To import multiple modules from a plugin, add additional specs for each import. For example, to import LazyVim core plugins and an optional plugin:

require("lazy").setup({
  spec = {
    { "LazyVim/LazyVim", import = "lazyvim.plugins" },
    { import = "lazyvim.plugins.extras.coding.copilot" },
  }
})

When you import specs, you can override them by simply adding a spec for the same plugin to your local specs, adding any keys you want to override / merge.

opts, dependencies, cmd, event, ft and keys are always merged with the parent spec. Any other property will override the property from the parent spec.

❌ 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.

8.3 KiB Raw Blame History