Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 36 ยท Neovim and Lua

Neovim: What Is Different

Learn what Neovim adds to Vim: Lua configuration, built-in LSP and Treesitter, a terminal, floating windows, XDG config paths, :checkhealth and how to migrate your vimrc.

Neovim is a fork of Vim that began in 2014 with the goal of modernizing the code base, making it easier to extend and letting other programs control it. It keeps Vim's editing model: everything you learned about modes, motions, operators, registers and macros works unchanged. What differs is what surrounds the editor, mainly configuration, extensibility and built-in features.

As in the rest of this chapter, Neovim cannot run on this site. Commands and file names below are described as the real editor behaves; the runnable blocks are labelled JavaScript stand-ins.

What Neovim adds

Why people switch

Lua A fast, small language for config
LSP Built-in language server client
Treesitter Parser-based highlighting

Same keys as Vim, a more modern engine.

1 / 2
  • Lua is a first-class language for configuration and plugins, next to Vim script. Plugins in Lua start faster and can use the editor's API directly.
  • Language Server Protocol client: diagnostics, go to definition, rename, hover and completion for most languages, without a heavy plugin.
  • Tree-sitter: incremental parsers give accurate syntax highlighting, folds and text objects. The grammars are installed with the nvim-treesitter plugin; the parsing library itself is built in.
  • Terminal emulator: :terminal starts a shell in a buffer, and terminal mode has its own mappings.
  • Floating windows and extmarks: windows drawn over others and virtual text, used for pickers, hover popups and inline diagnostics.
  • Asynchronous jobs and an RPC API (msgpack): you can control Neovim from scripts, other languages or GUIs. nvim --headless -c "..." runs it without a screen, useful for scripts and tests.
  • Better defaults: filetype detection, syntax, incsearch, hlsearch, hidden, mouse, wildmenu, autoindent, ruler and many others are on out of the box, and the defaults keep improving between releases. :help vim-differences lists them all.

Config location

Neovim does not read ~/.vimrc. It follows the XDG layout:

System Config directory
Linux, macOS ~/.config/nvim/
Windows %LOCALAPPDATA%\nvim\

The entry file is either init.lua or init.vim. Use one of them, not both. $XDG_CONFIG_HOME changes the base. From inside Neovim, :echo stdpath('config') prints the exact directory, stdpath('data') the place for plugin data (~/.local/share/nvim on Linux), stdpath('state') and stdpath('cache') the others, and :echo $MYVIMRC shows the init file in use.

JS Stand-in: where does Neovim look?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Your first init file

If you have a vimrc, you can start by sourcing it. Create ~/.config/nvim/init.vim:

VIM
set runtimepath^=~/.vim runtimepath+=~/.vim/after
let &packpath = &runtimepath
source ~/.vimrc

For a fresh start, create init.lua and set a few things:

LUA
vim.g.mapleader = " "
vim.opt.number = true
vim.opt.shiftwidth = 2
vim.opt.expandtab = true
vim.keymap.set("n", "<leader>w", "<cmd>write<cr>")

The next lessons explain every part of that file.

:checkhealth and troubleshooting

:checkhealth runs diagnostics for the core and for installed plugins: is a clipboard tool found, is Python or Node available for plugins that need them, is the nvim-treesitter parser set complete, are LSP servers on the path. Read it when something does not work; it names the missing piece. Other tools:

  • nvim --clean starts without your config and plugins.
  • nvim -u path/to/init.lua starts with a specific config, which is handy to test changes in a scratch directory.
  • :messages and :lua print(vim.inspect(vim.opt.runtimepath:get())) help to debug.
  • :help is excellent and includes a full Lua guide: :help lua-guide.
  • :Tutor starts a built-in interactive tutorial.

Migrating from Vim

  1. Check what you still need. Many options and mappings are Neovim defaults now, so your old vimrc can shrink.
  2. Keep Vim script where it works; you can mix: vim.cmd("set number") runs Vim script from Lua, and :lua runs Lua from the command line.
  3. Move to Lua gradually, one section at a time.
  4. Replace plugins that Neovim covers (LSP, Treesitter, a Lua statusline) with Lua-based equivalents when you are ready.
  5. Check compatibility notes: a few Vim features, like Vim9 script, do not exist in Neovim, and some defaults differ (for example Y yanks to the end of line in recent Neovim versions).

Architecture in one picture

flowchart LR
    UI["Terminal UI or GUI"] <-->|"msgpack RPC"| Core["Neovim core"]
    Core --> Lua["Lua runtime (LuaJIT)"]
    Core --> LSP["LSP client"]
    Core --> TS["Tree-sitter"]
    LSP <--> Srv["Language servers"]
    Lua --> Plug["Plugins"]

The editor core talks to the screen and to external tools over a protocol, which is why many GUIs and remote tools can embed Neovim.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does Neovim read its configuration on Linux by default?

    Neovim follows the XDG layout: ~/.config/nvim/. stdpath('config') prints the exact path.
  2. 2. Do Vim's modes, motions and operators change in Neovim?

    Neovim keeps Vim's editing language; the differences are mostly in configuration, extensibility and built-in features.
  3. 3. Which command diagnoses a broken setup, such as a missing clipboard provider?

    :checkhealth reports on the core and on plugins that provide health checks.
  4. 4. How do you start Neovim without your configuration?

    nvim --clean skips your init file and plugins, which isolates configuration problems.

Summary

  • Neovim is Vim's modern fork: same editing, plus Lua, LSP, Tree-sitter, terminal, floating windows and an RPC API.
  • Configuration lives in ~/.config/nvim/ (%LOCALAPPDATA%\nvim on Windows) as init.lua or init.vim.
  • :checkhealth, nvim --clean and stdpath() help you find and fix problems.
  • Migrate gradually; Vim script and Lua can coexist.

Next: Lua for Neovim Users