Lazy.nvim Optimization Skill

Lazy.nvim Optimization

Diagnose and fix Neovim startup performance through profiling and targeted lazy-loading.

Profiling Workflow

When a user reports slow startup, follow this sequence — don't skip to solutions.

Step 1: Measure Baseline

nvim --startuptime startup.log && tail -1 startup.log

Compare against targets:

< 30ms: Excellent
30-50ms: Good
50-100ms: Acceptable
100ms: Needs work

Step 2: Identify Slow Plugins

:Lazy profile

Look for plugins with load time > 10ms. These are your optimization targets. Sort by time, not alphabetically.

Also check the startup log for:

Files taking > 10ms to source
setup() functions taking > 5ms
Synchronous operations blocking startup

Step 3: Apply Lazy-Loading

For each slow plugin, choose the right trigger:

| Plugin Type | Trigger | Example | |-------------|---------|---------| | Has clear commands | cmd | cmd = "Telescope" | | Accessed via keybindings | keys | keys = { "<leader>e" } | | Language-specific | ft | ft = { "rust", "go" } | | Needed after UI renders | event = "VeryLazy" | UI enhancements | | Needed when editing | event = "BufReadPost" | Git signs, diagnostics | | Needed in insert mode | event = "InsertEnter" | Completion, autopairs | | Only used as dependency | lazy = true | plenary.nvim |

Step 4: Verify Improvement

nvim --startuptime startup-after.log && tail -1 startup-after.log

Compare total times. Then :Lazy profile to verify plugins load when expected.

What NOT to Lazy-Load

These need to load at startup — don't fight it:

Colorscheme — Set priority = 1000 so it loads first. Visible flash if deferred.
Treesitter — Needed for syntax highlighting immediately. Deferring causes flicker.
Statusline — Visible at startup. Deferring causes layout shift.
which-key — Only if it shows on startup. Otherwise can lazy-load.
LSP base setup — Though individual servers can lazy-load by filetype.

Common Bottlenecks

Synchronous system calls at startup:

-- Bad: blocks startup
vim.fn.system("git status")

-- Good: defer it
vim.defer_fn(function()
  vim.fn.system("git status")
end, 100)

Loading all LSP servers at once: Consider loading LSP servers per-filetype instead of all at startup. Each server you don't load saves 5-15ms.

Plugins without any trigger: A bare { "plugin/name" } spec loads at startup. Always add a trigger unless the plugin genuinely needs immediate availability.

Performance Checklist

Startup

[ ] Colorscheme has priority = 1000
[ ] File explorers load on cmd/keys
[ ] Git interfaces load on cmd/keys
[ ] Completion loads on InsertEnter
[ ] Language plugins load on filetype
[ ] UI enhancements load on VeryLazy

Runtime

[ ] Telescope uses fzf-native extension
[ ] Treesitter parsers installed only for used languages
[ ] LSP servers only for filetypes you use
[ ] No plugins duplicating built-in 0.10+ features

Config

[ ] No synchronous system calls at startup
[ ] setup() only runs when plugins load
[ ] Keymaps defined with plugin lazy-loading
[ ] Auto-commands use specific events, not "*"

Reference Files

For detailed information:

references/lazy-loading-decision-tree.md - Decision tree for choosing lazy-loading strategy
references/profiling-guide.md - Advanced profiling techniques

Agent Skills: Lazy.nvim Optimization

Install this agent skill to your local

Skill Files