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