2022-12-15 04:04:04 +08:00
# 💤 lazy.nvim
2022-12-15 05:10:45 +08:00
**lazy.nvim** is a modern plugin manager for Neovim.
2022-11-26 21:31:29 +08:00
2022-12-15 04:17:38 +08:00
2022-12-15 04:05:25 +08:00
2022-11-28 14:36:46 +08:00
## ✨ Features
2022-12-15 05:10:45 +08:00
- 📦 Manage all your Neovim plugins with a sleek and intuitive UI
- 🚀 Fast startup times thanks to automatic caching and bytecode compilation of lua modules.
2022-12-15 04:04:04 +08:00
- 💾 Partial clones instead of shallow clones
2022-12-15 05:10:45 +08:00
- 🔌 Automatic lazy-loading of lua modules and lazy-loading on events, commands, filetypes, and key mappings.
- ⏳ Automatically install missing plugins before starting up Neovim, allowing you to start using it right away.
2022-12-15 04:04:04 +08:00
- 💪 Async execution for improved performance
- 🛠️ No need to manually compile plugins
- 🧪 Correct sequencing of dependencies
- 📁 Configurable in multiple files
2022-12-15 21:34:08 +08:00
- 📚 Generates helptags of the headings in `README.md` files for plugins that don't have vimdocs
2022-12-15 05:10:45 +08:00
- 💻 Dev options and patterns for using local plugins
2022-12-15 04:04:04 +08:00
- 📊 Profiling tools to optimize performance
2022-12-15 05:10:45 +08:00
- 🔒 Lockfile `lazy-lock.json` to keep track of installed plugins
2022-12-15 04:04:04 +08:00
- 🔎 Automatically check for updates
- 📋 Commit, branch, tag, version, and full [Semver ](https://devhints.io/semver ) support
- 📈 Statusline component to see the number of pending updates
2022-12-15 04:24:51 +08:00
## ⚡️ Requirements
2022-12-18 18:58:40 +08:00
- Neovim >= **0.8.0** (needs to be built with **LuaJIT** )
2022-12-18 18:43:10 +08:00
- Built for **Linux** and **MacOS**
2022-12-18 18:58:40 +08:00
- Git >= **2.19.0** (for partial clones support)
2022-12-15 04:24:51 +08:00
2022-12-15 04:41:19 +08:00
## 📦 Installation
You can use the following Lua code to bootstrap **lazy.nvim**
2022-12-15 15:46:47 +08:00
<!-- bootstrap:start -->
2022-12-15 06:29:00 +08:00
2022-12-15 04:41:19 +08:00
```lua
2022-12-15 07:23:01 +08:00
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not vim.loop.fs_stat(lazypath) then
vim.fn.system({
"git",
"clone",
"--filter=blob:none",
"--single-branch",
2022-12-16 22:09:50 +08:00
"git@github.com:folke/lazy.nvim.git",
2022-12-15 07:23:01 +08:00
lazypath,
})
end
2022-12-16 22:09:50 +08:00
vim.opt.runtimepath:prepend(lazypath)
2022-12-15 04:41:19 +08:00
```
2022-12-15 15:46:47 +08:00
<!-- bootstrap:end -->
2022-12-15 06:29:00 +08:00
2022-12-15 04:57:21 +08:00
Next step is to add **lazy.nvim** to the top of your `init.lua`
2022-12-15 04:54:17 +08:00
```lua
-- You can use a lua module that contains your plugins.
-- All sub modules of the lua module will also be automatically loaded
-- This is the preferred setup so your plugin specs can be properly cached.
require("lazy").setup("config.plugins", {
2022-12-15 07:29:11 +08:00
-- add any optional configuration here
2022-12-15 04:54:17 +08:00
})
-- Alternatively you can specify a plugin list
require("lazy").setup({
"folke/neodev.nvim",
"folke/which-key.nvim",
{ "folke/neoconf.nvim", cmd = "Neoconf" },
}, {
2022-12-15 07:29:11 +08:00
-- add any optional configuration here
2022-12-15 04:54:17 +08:00
})
```
2022-12-15 07:23:01 +08:00
## 🔌 Plugin Spec
2022-12-15 15:46:47 +08:00
| Property | Type | Description |
| ---------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[1]` | `string?` | Short plugin url. Will be expanded using `config.git.url_format` |
| **dir** | `string?` | A directory pointing to a local plugin |
| **url** | `string?` | A custom git url where the plugin is hosted |
| **name** | `string?` | A custom name for the plugin used for the local plugin directory and as the dispay name |
| **dev** | `boolean?` | When `true` , a local plugin directory will be used instead. See `config.dev` |
| **lazy** | `boolean?` | When `true` , the plugin will only be loaded when needed. Lazy-loaded plugins are automatically loaded when their lua modules are `required` , or when one of the laz-loading handlers triggers |
| **enabled** | `boolean?` or `fun():boolean` | When `false` , or if the `function` returns false, then this plugin will not be used |
| **dependencies** | `LazySpec[]` | A list of plugin specs that should be loaded when the plugin loads. Dependencies are always lazy-loaded unless specified otherwise |
| **init** | `fun(LazyPlugin)` | `init` functions are always executed during startup |
| **config** | `fun(LazyPlugin)` | `config` is executed when the plugin loads |
| **build** | `fun(LazyPlugin)` | `build` is executed when a plugin is installed or updated |
| **branch** | `string?` | Branch of the repository |
| **tag** | `string?` | Tag of the repository |
| **commit** | `string?` | Commit of the repository |
| **version** | `string?` | Version to use from the repository. Full [Semver ](https://devhints.io/semver ) ranges are supported |
| **pin** | `boolean?` | When `true` , this plugin will not be included in updates |
| **event** | `string?` or `string[]` | Lazy-load on event |
| **cmd** | `string?` or `string[]` | Lazy-load on command |
| **ft** | `string?` or `string[]` | Lazy-load on filetype |
| **keys** | `string?` or `string[]` | Lazy-load on key mapping |
2022-12-18 21:23:02 +08:00
### Lazy Loading
**lazy.nvim** automagically lazy-loads Lua modules, so it is not needed to
specify `module=...` everywhere in your plugin specification. This mean that if
you have a plugin `A` that is lazy-loaded and a plugin `B` that requires a
module of plugin `A` , then plugin `A` will be loaded on demand as expected.
You can configure **lazy.nvim** to lazy-load all plugins by default with `config.defaults.lazy = true` .
Additionally, you can also lazy-load on **events** , **commands** ,
**file types** and **key mappings** .
Plugins will be lazy-loaded when one of the following is `true` :
- the plugin only exists as a dependency in your spec
- it has an `event` , `cmd` , `ft` or `cmd` key
- it defines an `init` method
- `config.defaults.lazy == true`
2022-12-18 21:26:24 +08:00
### Versioning
If you want to install a specific revision of a plugin, you can use `commit` ,
`tag` , `branch` , `version` .
The `version` property supports [Semver ](https://semver.org/ ) ranges:
- `*` : latest stable version (this excludes pre-release versions)
- `1.2.x` : any version that starts with `1.2` , such as `1.2.0` , `1.2.3` , etc.
- `^1.2.3` : any version that is compatible with `1.2.3` , such as `1.3.0` , `1.4.5` , etc., but not `2.0.0` .
- `~1.2.3` : any version that is compatible with `1.2.3` , such as `1.2.4` , `1.2.5` , but not `1.3.0` .
- `>1.2.3` : any version that is greater than `1.2.3` , such as `1.3.0` , `1.4.5` , etc.
- `>=1.2.3` : any version that is greater than or equal to `1.2.3` , such as `1.2.3` , `1.3.0` , `1.4.5` , etc.
- `<1.2.3` : any version that is less than `1.2.3` , such as `1.1.0` , `1.0.5` , etc.
- `<=1.2.3` : any version that is less than or equal to `1.2.3` , such as `1.2.3` , `1.1.0` , `1.0.5` , etc
> You can set `config.defaults.version = "*"` to install the latest stable
> version of plugins that support Semver.
2022-12-18 21:28:49 +08:00
### Examples
My personal dots:
- [init.lua ](https://github.com/folke/dot/blob/master/config/nvim/init.lua ) where I require `config.lazy`
- [config.lazy ](https://github.com/folke/dot/blob/master/config/nvim/lua/config/lazy.lua ) where I bootstrap and setup **lazy.nvim**
- [config.plugins ](https://github.com/folke/dot/blob/master/config/nvim/lua/config/plugins.lua ) is my main plugin config module
- Any submodule of [config.plugins (submodules) ](https://github.com/folke/dot/tree/master/config/nvim/lua/config/plugins ) will be automatically loaded as well.
Other examples:
2022-12-15 15:46:47 +08:00
<!-- spec:start -->
2022-12-15 07:23:01 +08:00
```lua
return {
-- the colorscheme should be available when starting Neovim
"folke/tokyonight.nvim",
-- I have a separate config.mappings file where I require which-key.
-- With lazy the plugin will be automatically loaded when it is required somewhere
{ "folke/which-key.nvim", lazy = true },
{
"nvim-neorg/neorg",
-- lazy-load on filetype
ft = "norg",
-- custom config that will be executed when loading the plugin
config = function()
require("neorg").setup()
end,
},
{
"dstein64/vim-startuptime",
-- lazy-load on a command
cmd = "StartupTime",
},
{
"hrsh7th/nvim-cmp",
-- load cmp on InsertEnter
event = "InsertEnter",
-- these dependencies will only be loaded when cmp loads
-- dependencies are always lazy-loaded unless specified otherwise
dependencies = {
"hrsh7th/cmp-nvim-lsp",
"hrsh7th/cmp-buffer",
},
config = function()
-- ...
end,
},
-- you can use the VeryLazy event for things that can
-- load later and are not important for the initial UI
{ "stevearc/dressing.nvim", event = "VeryLazy" },
{
"cshuaimin/ssr.nvim",
-- init is always executed during startup, but doesn't load the plugin yet.
-- init implies lazy loading
init = function()
vim.keymap.set({ "n", "x" }, "< leader > cR", function()
-- this require will automatically load the plugin
require("ssr").open()
end, { desc = "Structural Replace" })
end,
},
{
"monaqa/dial.nvim",
-- lazy-load on keys
keys = { "< C-a > ", "< C-x > " },
},
-- local plugins need to be explicitely configured with dir
{ dir = "~/projects/secret.nvim" },
-- you can use a custom url to fetch a plugin
{ url = "git@github.com:folke/noice.nvim.git" },
-- local plugins can also be configure with the dev option.
-- This will use ~/projects/noice.nvim/ instead of fetching it from Github
-- With the dev option, you can easily switch between the local and installed version of a plugin
{ "folke/noice.nvim", dev = true },
}
```
2022-12-15 15:46:47 +08:00
<!-- spec:end -->
2022-12-15 07:23:01 +08:00
2022-12-15 04:54:17 +08:00
## ⚙️ Configuration
**lazy.nvim** comes with the following defaults:
2022-12-15 15:46:47 +08:00
<!-- config:start -->
2022-12-15 07:23:01 +08:00
2022-12-15 04:54:17 +08:00
```lua
{
root = vim.fn.stdpath("data") .. "/lazy", -- directory where plugins will be installed
defaults = {
lazy = false, -- should plugins be lazy-loaded?
version = nil,
-- version = "*", -- enable this to try installing the latest stable versions of plugins
},
lockfile = vim.fn.stdpath("config") .. "/lazy-lock.json", -- lockfile generated after running update.
concurrency = nil, ---@type number limit the maximum amount of concurrent tasks
git = {
-- defaults for the `Lazy log` command
-- log = { "-10" }, -- show the last 10 commits
log = { "--since=1 days ago" }, -- show commits from the last 3 days
timeout = 120, -- kill processes that take more than 2 minutes
url_format = "https://github.com/%s.git",
},
dev = {
-- directory where you store your local plugin projects
path = vim.fn.expand("~/projects"),
---@type string[] plugins that match these patterns will use your local versions instead of being fetched from GitHub
patterns = {}, -- For example {"folke"}
},
install = {
-- install missing plugins on startup. This doesn't increase startup time.
missing = true,
-- try to load one of these colorschemes when starting an installation during startup
colorscheme = { "habamax" },
},
ui = {
-- The border to use for the UI window. Accepts same border values as |nvim_open_win()|.
border = "none",
icons = {
cmd = " ",
config = "",
event = "",
ft = " ",
init = " ",
keys = " ",
plugin = " ",
runtime = " ",
source = " ",
start = "",
task = "✔ ",
},
throttle = 20, -- how frequently should the ui process render events
},
checker = {
-- automcatilly check for plugin updates
enabled = false,
concurrency = nil, ---@type number? set to 1 to check for updates very slowly
notify = true, -- get a notification when new updates are found
frequency = 3600, -- check for updates every hour
},
performance = {
2022-12-15 04:58:55 +08:00
cache = {
enabled = true,
path = vim.fn.stdpath("state") .. "/lazy.state",
-- Once one of the following events triggers, caching will be disabled.
-- To cache all modules, set this to `{}` , but that is not recommended.
-- The default is to disable on:
-- * VimEnter: not useful to cache anything else beyond startup
-- * BufReadPre: this will be triggered early when opening a file from the command line directly
disable_events = { "VimEnter", "BufReadPre" },
},
2022-12-15 04:54:17 +08:00
reset_packpath = true, -- reset the package path to improve startup time
rtp = {
reset = true, -- reset the runtime path to $VIMRUNTIME and your config directory
---@type string[] list any plugins you want to disable here
disabled_plugins = {
-- "gzip",
-- "matchit",
-- "matchparen",
-- "netrwPlugin",
-- "tarPlugin",
-- "tohtml",
-- "tutor",
-- "zipPlugin",
},
},
},
2022-12-15 21:43:47 +08:00
-- lazy can generate helptags from the headings in markdown readme files,
-- so :help works even for plugins that don't have vim docs.
-- when the readme opens with :help it will be correctly displayed as markdown
readme = {
root = vim.fn.stdpath("state") .. "/lazy/readme",
files = { "README.md" },
-- only generate markdown helptags for plugins that dont have docs
skip_if_doc_exists = true,
},
2022-12-15 04:54:17 +08:00
}
```
2022-12-15 15:46:47 +08:00
<!-- config:end -->
2022-12-15 07:23:01 +08:00
2022-12-15 04:57:21 +08:00
## 🚀 Usage
2022-12-18 18:42:54 +08:00
You can manage all your plugins with the main `:Lazy` command.
Alternatively you can start any operation with a specific command, sub command or API function:
<!-- commands:start -->
| Command | Lua | Key Mapping | Description |
| --------------------------------- | --------------------------- | ----------- | ------------------------------------------------------ |
| `:Lazy home` or `:LazyHome` | `require("lazy").home()` | `<H>` | Go back to plugin list |
| `:Lazy install` or `:LazyInstall` | `require("lazy").install()` | `<I>` | Install missing plugins |
| `:Lazy update` or `:LazyUpdate` | `require("lazy").update()` | `<U>` | Update all plugins. This will also update the lockfile |
| `:Lazy sync` or `:LazySync` | `require("lazy").sync()` | `<S>` | Run install, clean and update |
| `:Lazy clean` or `:LazyClean` | `require("lazy").clean()` | `<X>` | Clean plugins that are no longer needed |
| `:Lazy check` or `:LazyCheck` | `require("lazy").check()` | `<C>` | Check for updates and show the log (git fetch) |
| `:Lazy log` or `:LazyLog` | `require("lazy").log()` | `<L>` | Show recent updates for all plugins |
| `:Lazy restore` or `:LazyRestore` | `require("lazy").restore()` | `<R>` | Updates all plugins to the state in the lockfile |
| `:Lazy profile` or `:LazyProfile` | `require("lazy").profile()` | `<P>` | Show detailed profiling |
| `:Lazy debug` or `:LazyDebug` | `require("lazy").debug()` | `<D>` | Show debug information |
| `:Lazy help` or `:LazyHelp` | `require("lazy").help()` | `<?>` | Toggle this help page |
| `:Lazy clear` or `:LazyClear` | `require("lazy").clear()` | | Clear finished tasks |
<!-- commands:end -->
2022-12-18 21:33:51 +08:00
## 🔒 Lockfile `lazy-lock.json`
After every **update** , the local lockfile is updated with the installed revisions.
It is recommended to have this file under version control.
If you use your Neovim config on multiple machines, using the lockfile, you can
ensure that the same version of every plugin is installed.
On the other machine, you can do `Lazy restore` , to update all your plugins to
the version from the lockfile
2022-12-15 04:57:21 +08:00
## 📊 Profiler
2022-12-15 04:07:06 +08:00
2022-12-15 04:11:01 +08:00
The profiling view shows you why and how long it took to load your plugins.
2022-12-15 04:07:06 +08:00
2022-12-15 04:57:21 +08:00
## 🪲 Debug
2022-12-15 04:08:28 +08:00
2022-12-15 04:11:01 +08:00
See an overview of active lazy-loading handlers and what's in the module cache
2022-12-15 04:08:28 +08:00
2022-12-15 04:11:01 +08:00
2022-11-29 22:25:09 +08:00
2022-12-16 22:10:05 +08:00
## ▶️ 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.
2022-12-18 18:43:10 +08:00
In practice this means that step 10 of [Neovim Initialization ](https://neovim.io/doc/user/starting.html#initialization ) is done by Lazy:
1. all files from `/plugin` and `/ftdetect` directories in you rtp are sourced (excluding `/after` )
2. all plugins with `lazy=false` are loaded. This includes sourcing `/plugin` and `/ftdetect` files. (`/after` will not be sourced yet)
3. all plugins' `/after/plugin` files are sourced
4. all `/after/plugin` files from the original rtp are sourced
5. all the plugins' `init()` functions are executed
Files from runtime directories are always sourced in alphabetical order.
2022-12-16 22:10:05 +08:00
2022-11-29 22:25:09 +08:00
## 📦 Differences with Packer
- **Plugin Spec**:
- `setup` => `init`
- `requires` => `dependencies`
- `as` => `name`
2022-12-01 18:32:52 +08:00
- `opt` => `lazy`
2022-12-01 20:33:55 +08:00
- `run` => `build`
2022-12-02 16:25:25 +08:00
- `lock` => `pin`
- `module` is auto-loaded. No need to specify
2022-12-01 06:15:14 +08:00
## 📦 Other Neovim Plugin Managers in Lua
- [packer.nvim ](https://github.com/wbthomason/packer.nvim )
- [paq-nvim ](https://github.com/savq/paq-nvim )
- [neopm ](https://github.com/ii14/neopm )
- [dep ](https://github.com/chiyadev/dep )
- [optpack.nvim ](https://github.com/notomo/optpack.nvim )
2022-12-04 00:46:10 +08:00
- [pact.nvim ](https://github.com/rktjmp/pact.nvim )
