Neovim Lua Configuration Guide 2026: Setup from Scratch with lazy.nvim

Why Lua Config in 2026?

Neovim's Lua API is the biggest reason to switch from Vim. Unlike Vimscript, Lua is a real programming language — fast, composable, and with first-class support in Neovim 0.10+.

This guide builds a Neovim config from zero using lazy.nvim, the modern plugin manager that loads plugins on-demand for instant startup.

By the end, you'll have a config that boots in under 50ms and rivals any IDE.

• Bootstrap lazy.nvim without any manual plugin installation
• Structure your config with modular Lua files
• Configure LSP, completion, and Treesitter
• Set up keymaps that feel like home

Installing Neovim from Scratch

Install Neovim 0.10 or later. On macOS: brew install neovim. On Linux: use your distro's package manager or build from source.

• Neovim 0.10+ (check with :version)
• Git (lazy.nvim clones plugins)
• A Nerd Font installed in your terminal
• ripgrep for fuzzy search (optional but recommended)
• A text editor to write config files — yes, you can use vim to configure nvim

Create the config directory structure:

~/.config/nvim/
├── init.lua          # Entry point
├── lua/
│   ├── core/         # Options, keymaps, autocmds
│   │   ├── init.lua
│   │   ├── options.lua
│   │   └── keymaps.lua
│   └── plugins/      # Plugin specs
│       └── init.lua

Bootstrapping lazy.nvim

The magic of lazy.nvim is that it bootstraps itself. Put this in init.lua and lazy.nvim installs itself on first launch:

-- bootstrap lazy.nvim
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",
"https://github.com/folke/lazy.nvim.git", lazypath
})
end
vim.opt.rtp:prepend(lazypath)
require("lazy").setup("lua/plugins")

Now create plugin specs in lua/plugins/. Each file returns a table — lazy.nvim loads them automatically:

-- lua/plugins/telescope.lua
return {
"nvim-telescope/telescope.nvim",
dependencies = { "nvim-lua/plenary.nvim" },
keys = {
{ "ff", "Telescope find_files", desc = "Find files" },
{ "fg", "Telescope live_grep", desc = "Live grep" },
},
}

Plugin Structure & Specs

The key to a great config is modular keymaps. Put your keybindings in lua/core/keymaps.lua and require them from init.lua.

• <leader>ff — find files (Telescope)
• <leader>fg — live grep
• <leader>e — toggle file explorer (nvim-tree)
• gd — go to definition (LSP)
• K — hover documentation (LSP)
• <C-h/j/k/l> — navigate splits

Set core options in lua/core/options.lua:

vim.opt.number = true
vim.opt.relativenumber = true
vim.opt.tabstop = 2
vim.opt.shiftwidth = 2
vim.opt.termguicolors = true
vim.opt.scrolloff = 8
vim.opt.signcolumn = "yes"

Keymaps, Options & Autocmds

Once your base config is solid, add these power-user touches:

• Use very_lazy event loading to defer plugin startup until first use
• Add cond = function() ... end to conditionally load plugins
• Set up Treesitter for syntax highlighting (see [[Neovim Treesitter]])
• Install nvim-cmp for autocomplete (see [[Neovim LSP Setup Guide]])
• Add which-key.nvim to discover keybindings interactively
• Configure lualine for a beautiful status bar

Config Errors & Linter

Common config issues and fixes:

• LSP not starting? Ensure you installed the language server: :Mason shows available servers
• Colors look wrong? Set vim.opt.termguicolors = true before loading your colorscheme
• Plugin not found? Run :Lazy sync to install/update all plugins
• Config errors? Run :luafile % to test the current file, or use luacheck
• Slow startup? Use :Lazy profile to find the culprit

Your Config is a Living Project

Your Neovim config is now a living project. Here's what to explore:

• Add LSP and completion (see [[Neovim LSP Setup Guide]])
• Install 15 essential plugins (see [[Neovim Plugins 2026]])
• Set up Treesitter for better highlighting (see [[Neovim Treesitter]])
• Add snippets for faster coding (see [[Neovim Snippets and Autopairs]])
• Debug with nvim-dap (see [[Neovim Debugging with nvim-dap]])