Updates & Maintenance

Understanding LazyVim Versioning

LazyVim has two version channels:

Channel	Default?	Behavior
Stable	✅ Default	Uses latest tagged release of LazyVim and lazy.nvim
Dev	❌ Opt-in	Tracks main branch — latest features, may break

Switch to Dev Channel

lua/plugins/core.lua

return {
  { "folke/lazy.nvim", version = false },   -- Track main branch
  { "LazyVim/LazyVim", version = false },    -- Track main branch
}

Updating Plugins

Using the Lazy UI

:Lazy          ← Open plugin manager

Inside the UI:

Key	Action
I	Install all missing plugins
U	Update all plugins to latest
S	Sync (install + update + clean)
C	Clean unused plugins
X	Delete all plugins and reinstall
p	Profile startup time
l	View changelog
q	Close
?	Show all keymaps

Safe Update Workflow

1. :Lazy                       ← Open the UI
2. Press `U`                   ← Update all plugins
3. Watch for errors (red text) ← If a plugin fails, note the name
4. Press `l`                   ← View the changelog for breaking changes
5. :LazyVim                    ← Check LazyVim news/breaking changes
6. Restart Neovim               ← Verify everything works

Command-Line Updates

:Lazy update       " Update all plugins
:Lazy sync         " Install missing + update + clean unused
:Lazy clean        " Remove plugins not in your spec
:Lazy check        " Check for available updates
:Lazy log          " View changelog of last update
:Lazy profile      " Show startup time breakdown

The Lock File (lazy-lock.json)

Located at ~/.config/nvim/lazy-lock.json. This file records the exact commit hash of every installed plugin.

Example

{
  "LazyVim/LazyVim": { "commit": "a1b2c3d4..." },
  "folke/trouble.nvim": { "commit": "e5f6g7h8..." },
  "nvim-telescope/telescope.nvim": { "commit": "i9j0k1l2..." }
}

Purpose

• Reproducibility: Everyone on your team gets the same plugin versions
• Rollback: If an update breaks something, restore the old lockfile
• CI/CD: Use in automated setups to ensure consistent behavior

Managing the Lock File

# Add to git for reproducibility
cd ~/.config/nvim
git add lazy-lock.json
git commit -m "chore: lock plugin versions"

Rollback a Broken Update

# Revert the lockfile to previous version
cd ~/.config/nvim
git checkout HEAD~1 -- lazy-lock.json

# Then inside Neovim:
:Lazy sync

LazyVim News & Breaking Changes

LazyVim shows news when there are breaking changes or new features. You can also check manually:

:LazyVim          " Show LazyVim news/changelog
<leader>L         " Open LazyVim changelog

Configure what news to show:

lua/plugins/core.lua

return {
  {
    "LazyVim/LazyVim",
    opts = {
      news = {
        lazyvim = true,   -- Show LazyVim news (default)
        neovim = false,   -- Don't show Neovim news
      },
    },
  },
}

Backup & Restore

Full Config Backup

backup.sh

cd ~/.config
tar -czf nvim-backup-$(date +%Y%m%d).tar.gz nvim/

Selective Backup

backup-selective.sh

# Backup config (excluding plugins)
cp -r ~/.config/nvim ~/.config/nvim-backup-$(date +%Y%m%d)

# Backup the lockfile (version pinning)
cp ~/.config/nvim/lazy-lock.json ~/lazy-lock-backup.json

Full Restore

restore.sh

# Restore config
rm -rf ~/.config/nvim
cp -r ~/nvim-backup-20260724 ~/.config/nvim

# Then inside Neovim:
:Lazy sync

Checking Plugin Health

:LazyHealth          " Load all plugins and check status
:checkhealth         " Neovim's built-in health check
:checkhealth lazy    " Check lazy.nvim specifically
:checkhealth mason   " Check Mason LSP/linter tools

Troubleshooting Update Issues

Problem	Likely Cause	Fix
:Lazy shows 🔴 red plugin	Plugin broke after update	Rollback lockfile or disable the plugin
Startup slower after update	Hugely increased plugin	:Lazy profile to find culprit
LSP not working after update	LSP server updated	:Mason → update the server
Neovim crashes on open	Config compatibility	:Lazy → X to reinstall all plugins
Keymaps not working	LazyVim changed defaults	Check :LazyVim news for breaking changes

Migration from Other Configs

From Vanilla Neovim

1. Backup your old config
2. Install LazyVim starter
3. Copy your old lua/plugins/*.lua specs to new config
4. If you used the same plugin, LazyVim's defaults merge with yours
5. If you used a different plugin manager, convert specs to lazy.nvim format

From Other Distributions (NvChad, AstroNvim, etc.)

1. Export your keymaps and options you depend on
2. Install LazyVim starter fresh
3. Add only the plugins you actually need as extras or custom specs
4. Resist importing everything — LazyVim already includes 95% of what you need

Key Migration Tips

• LazyVim uses <space> as leader. If your old config used a different leader, change it in lua/config/options.lua
• LazyVim's opts merging means you don't need to copy full plugin configs
• Search the Extras catalog before adding a plugin manually — it might already exist

Restoring a Session After Update

If an update breaks your session:

# Remove saved session
rm -rf ~/.local/share/nvim/sessions/

Or from within Neovim:

:lua require("persistence").stop()   " Stop auto-saving current session
:lua require("persistence").load({ last = true })  " Load last good session

Related

• Installation
• Configuration
• Sessions & Workspace