Skip to main content

Adding Custom Plugins to LazyVim

LazyVim is powered by lazy.nvim, making it incredibly simple to add new plugins, override existing ones, or completely disable default functionality you don't need.

Where to add plugins​

All custom plugins should be placed in the lua/plugins/ directory. You can organize them however you like:

  • One massive plugins.lua file.
  • Individual files per plugin (e.g., lua/plugins/harpoon.lua).

LazyVim automatically loads all .lua files in the lua/plugins/ directory and merges them.

Adding a brand new plugin​

To add a plugin that isn't included in LazyVim, just return its spec in a file under lua/plugins/.

Example: Adding Harpoon (lua/plugins/harpoon.lua):

return {
  "ThePrimeagen/harpoon",
  keys = {
    { "<leader>ha", function() require("harpoon.mark").add_file() end, desc = "Add to Harpoon" },
    { "<leader>hm", function() require("harpoon.ui").toggle_quick_menu() end, desc = "Harpoon Menu" },
  },
}

Overriding a LazyVim default plugin​

To change the configuration of a plugin that LazyVim already installs, you don't need to rewrite the entire setup. Just define the plugin with the same name and provide your opts. LazyVim will deep merge your options with the defaults.

Example: Overriding Telescope options (lua/plugins/telescope.lua):

return {
  "nvim-telescope/telescope.nvim",
  opts = {
    defaults = {
      layout_strategy = "horizontal",
      layout_config = { prompt_position = "top" },
      sorting_strategy = "ascending",
    },
  },
}

Disabling a LazyVim default plugin​

If you prefer not to use a plugin that comes pre-configured, you can simply set enabled = false.

Example: Disabling the default statusline (lualine) (lua/plugins/lualine.lua):

return {
  "nvim-lualine/lualine.nvim",
  enabled = false,
}

The spec merging rules​

LazyVim uses lazy.nvim's powerful merging capabilities:

  • opts: Deeply merged. Tables are combined, strings/booleans are overwritten.
  • keys: Appended. Your keys are added to the default keys. If you use the same key, yours overrides the default.
  • dependencies: Appended.