+ Install + · + Configure + · + Docs +
+ + + + **lazy.nvim** is a modern plugin manager for Neovim. - + ## ✨ Features -- 📦 Manage all your Neovim plugins with a sleek and intuitive UI -- 🚀 Fast startup times thanks to automatic caching and bytecode compilation of lua modules. +- 📦 Manage all your Neovim plugins with a powerful UI +- 🚀 Fast startup times thanks to automatic caching and bytecode compilation of Lua modules - 💾 Partial clones instead of shallow clones -- 🔌 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. +- 🔌 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 - 💪 Async execution for improved performance - 🛠️ No need to manually compile plugins - 🧪 Correct sequencing of dependencies @@ -22,315 +54,16 @@ - 🔎 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 - -## 📄 Table of Contents - - - -- [⚡️ Requirements](#-requirements) - - [📦 Installation](#-installation) - - [🔌 Plugin Spec](#-plugin-spec) - - [⚙️ Configuration](#-configuration) - - [🚀 Usage](#-usage) - - [📊 Profiler](#-profiler) - - [🪲 Debug](#-debug) - - [▶️ Startup Sequence](#-startup-sequence) - - [📦 Differences with Packer](#-differences-with-packer) - - [📦 Other Neovim Plugin Managers in Lua](#-other-neovim-plugin-managers-in-lua) - - +- 🎨 Automatically lazy-loads colorschemes ## ⚡️ Requirements -- Neovim >= **0.8.0** +- Neovim >= **0.8.0** (needs to be built with **LuaJIT**) +- Git >= **2.19.0** (for partial clones support) +- a [Nerd Font](https://www.nerdfonts.com/) **_(optional)_** +- [luarocks](https://luarocks.org/) to install rockspecs. + You can remove `rockspec` from `opts.pkg.sources` to disable this feature. -## 📦 Installation +## 🚀 Getting Started -You can use the following Lua code to bootstrap **lazy.nvim** - - - -```lua -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", - "git@github.com:folke/lazy.nvim.git", - lazypath, - }) - end - vim.opt.runtimepath:prepend(lazypath) -``` - - - -Next step is to add **lazy.nvim** to the top of your `init.lua` - -```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", { - -- add any optional configuration here -}) - --- Alternatively you can specify a plugin list -require("lazy").setup({ - "folke/neodev.nvim", - "folke/which-key.nvim", - { "folke/neoconf.nvim", cmd = "Neoconf" }, - }, { - -- add any optional configuration here -}) -``` - -## 🔌 Plugin Spec - -| 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 | - - - -```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" }, "
+ 
+ 
+ 
+ 
+ 
+ 
+
-
-
-FEATURES *lazy.nvim-features*
+✨ FEATURES *lazy.nvim-🚀-getting-started-✨-features*
+
+- 📦 Manage all your Neovim plugins with a powerful UI
+- 🚀 Fast startup times thanks to automatic caching and bytecode compilation of Lua modules
+- 💾 Partial clones instead of shallow clones
+- 🔌 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
+- 💪 Async execution for improved performance
+- 🛠️ No need to manually compile plugins
+- 🧪 Correct sequencing of dependencies
+- 📁 Configurable in multiple files
+- 📚 Generates helptags of the headings in `README.md` files for plugins that don’t have vimdocs
+- 💻 Dev options and patterns for using local plugins
+- 📊 Profiling tools to optimize performance
+- 🔒 Lockfile `lazy-lock.json` to keep track of installed plugins
+- 🔎 Automatically check for updates
+- 📋 Commit, branch, tag, version, and full Semver
-image
-
-
-
+ LazyButtonActive Visual
-🪲 DEBUG *lazy.nvim-🪲-debug*
+ LazyComment Comment
-See an overview of active lazy-loading handlers and what’s in the module
-cache
+ LazyCommit @variable.builtin commit ref
-
-image
-
-
-
+ LazyCommitIssue Number
-STARTUP SEQUENCE *lazy.nvim-startup-sequence*
+ LazyCommitScope Italic conventional commit
+ scope
+
+ LazyCommitType Title conventional commit
+ type
+
+ LazyDimmed Conceal property
+
+ LazyDir @markup.link directory
+
+ LazyError DiagnosticError task errors
+
+ LazyH1 IncSearch home button
+
+ LazyH2 Bold titles
+
+ LazyInfo DiagnosticInfo task errors
+
+ LazyItalic { italic = true }
+
+ LazyLocal Constant
+
+ LazyNoCond DiagnosticWarn unloaded icon for a
+ plugin where cond() was
+ false
+
+ LazyNormal NormalFloat
+
+ LazyProgressDone Constant progress bar done
+
+ LazyProgressTodo LineNr progress bar todo
+
+ LazyProp Conceal property
+
+ LazyReasonCmd Operator
+
+ LazyReasonEvent Constant
+
+ LazyReasonFt Character
+
+ LazyReasonImport Identifier
+
+ LazyReasonKeys Statement
+
+ LazyReasonPlugin Special
+
+ LazyReasonRequire @variable.parameter
+
+ LazyReasonRuntime @macro
+
+ LazyReasonSource Character
+
+ LazyReasonStart @variable.member
+
+ LazySpecial @punctuation.special
+
+ LazyTaskOutput MsgArea task output
+
+ LazyUrl @markup.link url
+
+ LazyValue @string value of a property
+
+ LazyWarning DiagnosticWarn task errors
+ -----------------------------------------------------------------------
+
+==============================================================================
+7. 🚀 Usage *lazy.nvim-🚀-usage*
+
+
+▶️ STARTUP SEQUENCE *lazy.nvim-🚀-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.
+In practice this means that step 10 of |Neovim Initialization| is done by Lazy:
-DIFFERENCES WITH PACKER *lazy.nvim-differences-with-packer*
+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.
-- **Plugin Spec**:
- - `setup` => `init`
- - `requires` => `dependencies`
- - `as` => `name`
- - `opt` => `lazy`
- - `run` => `build`
- - `lock` => `pin`
- - `module` is auto-loaded. No need to specify
+🚀 COMMANDS *lazy.nvim-🚀-usage-🚀-commands*
+
+Plugins are managed with the `:Lazy` command. Open the help with `` to see
+all the key mappings.
+
+You can press `
-image
-