What is Neovim?
Neovim is a hyperextensible Vim-based text editor designed for the modern developer. It keeps Vim's modal editing model and keybindings but adds a first-class Lua scripting API, built-in LSP client, async job control, and a rich plugin ecosystem. It runs in the terminal and is highly configurable.
Modal Editing
Different modes for navigation, editing, and commands β keeps hands on the keyboard
Lua Config
Full Lua scripting API β configs are real programs, not just config files
LSP Built-in
Native Language Server Protocol client β go-to-def, hover, diagnostics, formatting
Treesitter
Incremental syntax trees β precise highlighting, text objects, and folding
Performance
Async by default β UI never blocks, large files open instantly
Free & Open
Apache 2.0 / Vim license. Zero cost, fully open source, runs anywhere
Vim vs Neovim
| Feature | Vim | Neovim |
|---|---|---|
| Config language | VimScript | Lua (+ VimScript) |
| LSP support | Via plugin (CoC) | Built-in LSP client |
| Async execution | Limited | Full async via libuv |
| Treesitter | No | Built-in |
| Plugin API | VimScript API | Lua API + VimScript compat |
| Floating windows | No | Yes (popups, UI plugins) |
| Terminal emulator | Basic | Full terminal mode |
| Remote plugins | No | Yes (RPC msgpack) |
| Health checks | No | :checkhealth built-in |
Modes β The Foundation
Understanding modes is the single most important concept in Neovim. Every key press does something different depending on which mode you're in.
Normal Mode
Navigate, copy, delete, and run commands. This is where you spend most time.
- Enter from Insert: Esc or Ctrl+[
- Every key is a command β no text insertion
- Hjkl for movement, operators like d, c, y
Insert Mode
Where you actually type text. Enter with i, a, o, I, A, O.
- i β insert before cursor
- a β insert after cursor
- o / O β new line below/above
- I / A β start/end of line
Visual Mode
Select text for operations. Three variants:
- v β character visual
- V β line visual
- Ctrl+v β block visual (column select)
- Then apply operators: d, y, c, >, <, =
Command Mode
Run commands, search, substitute. Enter with :.
- :w β save
- :q β quit
- :wq β save and quit
- :s/old/new/g β substitute
- /pattern β search
Terminal Mode
Run a real terminal inside Neovim. Enter with :term, exit with Ctrl+\ Ctrl+n.
- Full shell inside a buffer
- Switch to Normal with Ctrl+\ Ctrl+n
- Popular with toggleterm.nvim
Replace Mode
Overwrite characters in place. Enter with R from Normal mode.
- r β replace single character
- R β enter replace mode (type over)
Essential Keybindings
These are the most important keybindings to learn. Master these before adding plugins. All keybindings below work in NORMAL mode unless noted.
Motion & Navigation
| Key | Action | Notes |
|---|---|---|
| h j k l | Left / Down / Up / Right | Never use arrow keys |
| w / b | Next / prev word start | W/B = WORD (whitespace-delimited) |
| e / ge | Next / prev word end | |
| 0 / ^ / $ | Line start / first non-blank / line end | |
| gg / G | Top / bottom of file | 42G = jump to line 42 |
| Ctrl+d / Ctrl+u | Scroll half page down / up | Most common scrolling |
| Ctrl+f / Ctrl+b | Full page down / up | |
| % | Jump to matching bracket | Works on (, [, { |
| f{char} / F{char} | Find char forward / backward on line | ; repeat, , reverse |
| t{char} / T{char} | Till char forward / backward | Cursor stops before char |
| * / # | Search word under cursor fwd / back | Very fast for symbol search |
| zz / zt / zb | Center / top / bottom cursor line | |
| `` / '' | Jump back to last position | Ctrl+o / Ctrl+i = jump list |
Editing Operators & Text Objects
[count] operator [text-object/motion]. E.g. d2w = delete 2 words, ci" = change inside quotes.
| Key | Action | Examples |
|---|---|---|
| d | Delete (cut) | dw word, dd line, D to end |
| c | Change (delete + insert) | cw word, cc line, C to end |
| y | Yank (copy) | yw word, yy line, y$ to end |
| p / P | Paste after / before cursor | |
| u / Ctrl+r | Undo / Redo | Neovim has persistent undo |
| . | Repeat last change | One of the most powerful keys |
| x / X | Delete char under / before cursor | |
| r{char} | Replace char under cursor | |
| ~ | Toggle case | gu{motion} lowercase, gU uppercase |
| > / < | Indent / de-indent | >> line, =% auto-indent block |
| J | Join lines |
Text Objects (combine with d, c, y, v)
| Object | Meaning | i = inner, a = around |
|---|---|---|
| iw / aw | Word | iw = word only, aw = word + space |
| i" / a" | Double quoted string | ci" = change inside quotes |
| i' / a' | Single quoted string | |
| i( / a( | Parentheses | Also ib / ab |
| i{ / a{ | Curly braces | Also iB / aB |
| i[ / a[ | Square brackets | |
| it / at | HTML/XML tag | cit = change inside tag |
| ip / ap | Paragraph | |
| is / as | Sentence |
Windows, Tabs & Buffers
| Key | Action |
|---|---|
| :sp / :vsp | Horizontal / vertical split |
| Ctrl+w h/j/k/l | Move between splits |
| Ctrl+w = | Equalize split sizes |
| Ctrl+w q | Close split |
| :tabnew / gt / gT | New tab / next tab / prev tab |
| :bn / :bp | Next / prev buffer |
| :bd | Delete (close) buffer |
| :ls | List all open buffers |
Configuration
Neovim looks for config in ~/.config/nvim/. The entry point is
init.lua. All configuration is written in Lua.
Recommended Directory Structure
Core Options (options.lua)
Keymaps in Lua (keymaps.lua)
Plugin Manager β lazy.nvim
lazy.nvim is the current standard plugin manager for Neovim. It features lazy-loading by default (plugins only load when needed), a beautiful UI, lockfile for reproducibility, and fast startup times.
Bootstrap lazy.nvim
Plugin Spec Examples
lazy.nvim Key Commands
| Command | Action |
|---|---|
| :Lazy | Open lazy UI (install/update/sync) |
| :Lazy sync | Update all plugins to latest |
| :Lazy update | Update plugins (keeping lazy-lock.json) |
| :Lazy clean | Remove unused plugins |
| :Lazy profile | Show plugin load times |
| :Lazy log | Show recent plugin changes |
Popular Plugins
π LSP Stack (Code Intelligence)
The LSP stack gives you IDE features: go-to-definition, hover docs, diagnostics, rename, code actions. Three components work together:
mason.nvim
Package manager for LSP servers, DAP adapters, linters, and formatters. Install with :Mason.
nvim-lspconfig
Community configs for 100+ language servers. Handles server startup, capabilities, and default keymaps.
conform.nvim
Fast, async code formatter. Supports prettier, black, stylua, gofmt, and 50+ more. Replaces null-ls for formatting.
nvim-lint
Async linting via external linters (eslint, pylint, shellcheck). Pairs with conform.nvim β one for format, one for lint.
β Autocompletion
nvim-cmp
The standard completion engine. Aggregates sources: LSP, snippets, buffer words, file paths. Highly configurable.
blink.cmp
New faster completion engine written in Rust. Up to 10x faster than nvim-cmp. Growing rapidly in popularity.
LuaSnip
Powerful snippet engine. Works with nvim-cmp. Supports VSCode snippets, LuaSnip format, and dynamic snippets.
friendly-snippets
Community snippet collection for 50+ languages. Load with LuaSnip's VSCode loader β instant snippet library.
π Telescope β Fuzzy Finder
Telescope is the most popular Neovim plugin. A fuzzy finder over lists β files, buffers, git commits, LSP symbols, keymaps, anything.
telescope.nvim
Highly extensible fuzzy finder. 100+ built-in pickers. Built on top of plenary.nvim.
telescope-fzf-native
C-based fzf sorter for Telescope. 10-50x faster than the default Lua sorter. Always install this.
π³ Treesitter β Syntax Intelligence
nvim-treesitter
Incremental parsing for 100+ languages. Provides precise syntax highlighting, indentation, and text objects. Far superior to regex-based highlighting.
nvim-treesitter-textobjects
Adds syntax-aware text objects: if (inside function), ac (around class), ]m (next method).
nvim-treesitter-context
Shows the current function/class context at the top of the screen as you scroll through long files.
π File Tree Explorer
neo-tree.nvim
Modern file tree with buffers, git status, filesystem. Floating or sidebar modes. Most popular choice today.
nvim-tree.lua
Fast, icon-rich file tree. Alternative to neo-tree. Simpler but slightly less feature-rich. Good choice too.
oil.nvim
Edit filesystem like a buffer. Navigate directories as text files, create/rename/delete by editing buffer content.
π Git Integration
gitsigns.nvim
Shows git hunk indicators in the sign column (+/-/~). Inline blame, stage hunks, preview diffs β all inside Neovim.
vim-fugitive
The classic Git integration. Run any git command with :G. Interactive staging with :Git, diff with :Gdiff.
lazygit.nvim
Opens lazygit in a floating terminal inside Neovim. Best of both worlds β full lazygit TUI without leaving the editor.
diffview.nvim
Beautiful side-by-side diffs and git history browser. Essential for code reviews inside Neovim.
π¨ UI & UX Enhancement
lualine.nvim
Fast, configurable statusline in Lua. Shows mode, file, git branch, LSP diagnostics, location. Many built-in themes.
bufferline.nvim
Visual tab/buffer line at the top. Shows open buffers as tabs with icons and close buttons. Essential for multi-file work.
which-key.nvim
Popup showing available keymaps after a prefix key (e.g., press <leader> and wait). Discovers forgotten keymaps instantly.
noice.nvim
Completely replaces the cmdline, popup messages, and notifications with modern floating UI. Makes Neovim look like VS Code.
alpha-nvim
Greeter/dashboard shown when Neovim opens with no file. Shows recent files, quick actions, and ASCII art.
indent-blankline.nvim
Shows indent guides (vertical lines) and highlights the current indent scope. Makes deeply nested code readable.
catppuccin
Most popular Neovim colorscheme. 4 flavors: latte, frappΓ©, macchiato, mocha. Integrates with all major plugins.
tokyonight.nvim
Classic dark blue theme by folke. 4 styles: night, storm, moon, day. Excellent plugin integration. Very popular.
β‘ Coding Helpers
nvim-autopairs
Auto-closes brackets, quotes, and tags. Integrates with nvim-cmp so accepted completions don't double-pair.
Comment.nvim
Smart commenting with correct comment syntax per language. Treesitter integration for embedded languages.
nvim-surround
Add, change, delete surrounding characters. The spiritual successor to tpope's vim-surround, written in Lua.
flash.nvim
Enhanced navigation with jump labels. Type a few chars, jump exactly to the match with a label key. Replaces hop/leap.
toggleterm.nvim
Persistent toggleable terminal(s). Float, horizontal, vertical, or tab. Send lines from buffer to terminal.
trouble.nvim
Pretty diagnostics, LSP references, TODOs panel. Aggregates all errors/warnings in a browsable list below the editor.
todo-comments.nvim
Highlights TODO, FIXME, HACK, NOTE comments and makes them searchable via Telescope or Trouble.
mini.nvim
A collection of 40+ small, focused Lua modules. Pick exactly what you need: mini.files, mini.ai, mini.pairs, mini.animate.
Distributions β Pre-built Configs
If building from scratch feels overwhelming, start with a distribution. They provide a full IDE-like experience out of the box. You can customize from there, or gradually learn how they work.
| Distribution | Philosophy | Beginner-Friendly | Customizable | Best For |
|---|---|---|---|---|
| LazyVim | Batteries included, lazy.nvim-based, opinionated defaults | β Yes | Very High | Most users β great starting point |
| AstroNvim | Community-maintained, modular, lazy.nvim-based | β Yes | Very High | Community plugins, "AstroCommunity" |
| NvChad | Fast startup, beautiful UI, minimal base | Moderate | Medium | Speed-focused users who love pretty UI |
| kickstart.nvim | Single-file teaching config β read every line | β Best | Start here | Recommended for learning β understand everything |
| Custom (from scratch) | Build exactly what you need, nothing else | Hard | Total | Experienced users, minimalists |
Best Practices & Learning Tips
Learn Vim motions first β before plugins
Run vimtutor in your terminal. Do it twice. Master hjkl, w/b/e, f/t, ciw, dd, yy, p before installing anything. Plugins amplify skills you already have.
Use kickstart.nvim as your starting config
Clone it, read every comment, run it. This teaches you why each option exists. Don't copy large configs you don't understand β you won't know how to debug them.
Install plugins one at a time
Add one plugin, learn it for a week, then add the next. Installing 50 plugins at once is overwhelming and leads to unmaintained bloat. Start with: LSP + Telescope + Treesitter + a colorscheme.
Set a leader key and be consistent
Use Space as leader (most popular). Group your keymaps logically: <leader>f = find, <leader>g = git, <leader>c = code, <leader>u = UI. Use which-key.nvim to document them.
Use :checkhealth regularly
Run :checkhealth after installing plugins or language servers. It diagnoses missing dependencies, incorrect paths, and configuration errors before they become mysterious bugs.
Keep your config in Git
Put ~/.config/nvim in a git repo. This lets you sync between machines, roll back bad changes, and track what you've changed. Commit often with descriptive messages.
Starter Plugin Set (Minimal but Powerful)
:Lazy profile to see which plugins slow down startup. Aggressively lazy-load everything β use event, cmd, or keys triggers instead of loading eagerly.
:help is incredibly comprehensive. :help usr_01.txt starts the official Vim manual. :Telescope help_tags makes it searchable.