Neovim Without Plugins — A Practical Guide

1. What Neovim Is (and why it's different from Vim)

Neovim is a fork of Vim, started in 2014, with two goals: modernize the codebase (Vim's C code is decades old and hard to extend) and expose a proper API so tools can embed and script the editor. In practice, that means:

• Modal editing — the same core idea as Vim: you spend most of your time in a normal mode built for navigating and manipulating text, not typing it, and you drop into insert mode only when you actually need to type. This is the single biggest mental shift coming from editors like VS Code or Notepad.
• Built-in Lua — Neovim embeds a Lua interpreter, so configuration and scripting can be written in a real programming language instead of Vimscript (Vimscript still works too).
• Built-in LSP client, terminal, and more — things that required plugins in old Vim now ship in the core binary.

2. Installing Neovim

Neovim's own install guide is at neovim.io/doc/install — worth bookmarking, since exact package names occasionally shift.

Windows

# Winget (built into modern Windows)
winget install Neovim.Neovim

# Chocolatey
choco install neovim

# Scoop
scoop install neovim

macOS

# Homebrew (recommended)
brew install neovim

# MacPorts
sudo port install neovim

Linux

# Ubuntu / Debian — from standard repos (may lag behind latest release)
sudo apt install neovim

# Ubuntu — official PPA for an up-to-date stable build
sudo add-apt-repository ppa:neovim-ppa/stable
sudo apt-get update
sudo apt-get install neovim

# Fedora
sudo dnf install -y neovim python3-neovim

# Arch Linux
sudo pacman -S neovim

# Distro-agnostic: Flatpak
flatpak install flathub io.neovim.nvim

# Distro-agnostic: Snap
sudo snap install nvim --classic

Verifying the install

nvim --version
nvim

The second command should open the editor to a blank buffer. Type :q and press Enter to quit — that single command solves the most-asked Neovim question ("how do I exit this thing").

3. Core Concept — Modes

Everything in Neovim hinges on which mode you're in. Get this and the rest clicks into place; skip it and every shortcut list looks arbitrary.

4. Essential Motions and Editing

These are grouped by what they're for, not alphabetically, because that's how you'll actually reach for them.

Entering Insert mode

Moving around

Editing — the verb + motion grammar

Editing commands are verbs, motions are nouns, and you combine them:

Text objects

Text objects let you operate on semantic chunks — words, sentences, quoted strings, parenthesized groups — without having to position the cursor exactly:

Other frequently used commands

5. Built-in Features People Assume Need a Plugin

File explorer — netrw

Neovim ships a built-in file browser called netrw:

• :Explore (or :Ex) — open a file explorer in the current window
• :Vexplore / :Sexplore — same, but in a vertical/horizontal split
• Inside netrw: Enter opens the file/folder under cursor, - goes up a directory, % creates a new file, d creates a directory, D deletes

Built-in terminal

• :terminal (or :term) — opens a real terminal in a Neovim buffer
• Press Ctrl+\ then Ctrl+n to drop back to Normal mode without killing the shell
• Press i to go back into the terminal to type
• Combine with :split / :vsplit to keep the terminal in its own pane

Marks and jumps

• ma — set mark a at the cursor (any lowercase letter works)
• `a — jump to exact mark a position; 'a jumps to start of that line
• Ctrl+o / Ctrl+i — walk backward/forward through jump history
• `` — jump back to position before the last jump (press backtick twice)

Macros

Record a sequence of edits once, replay it many times:

1. qa — start recording into register a
2. Do the edit sequence normally
3. q — stop recording
4. @a — replay once
5. 5@a — replay 5 more times; @@ repeats whichever macro you last ran

Registers (multiple clipboards)

• "ayy — yank a line into register a
• "ap — paste from register a
• :reg — see everything in every register
• "+yy — copy a line to the OS clipboard (pasteable in other apps)
• "+p — paste from the OS clipboard

Diff mode

nvim -d file1 file2

Or use :diffthis in two split windows for a full built-in diff/merge view.

Search and replace

/searchterm        # search forward
?searchterm        # search backward
n / N              # next / previous match
:%s/old/new/g      # replace all occurrences in file
:%s/old/new/gc     # replace with confirmation on each match
:5,10s/old/new/g   # replace only in lines 5–10

6. A Minimal Plugin-Free init.lua

Meaningfully better defaults without installing a single plugin:

Config file location:

• Linux/macOS: ~/.config/nvim/init.lua
• Windows: ~/AppData/Local/nvim/init.lua

-- ~/.config/nvim/init.lua
local opt = vim.opt

-- Line numbers: absolute on current line, relative elsewhere
-- (relative numbers make 5j / 5dd-style counted motions trivial to judge)
opt.number = true
opt.relativenumber = true

-- Indentation: 2 spaces, no tabs, match indent on new lines
opt.expandtab = true
opt.shiftwidth = 2
opt.tabstop = 2
opt.smartindent = true

-- Search: case-insensitive unless you type a capital letter
opt.ignorecase = true
opt.smartcase = true
opt.incsearch = true   -- show matches as you type
opt.hlsearch = true    -- highlight all matches

-- Quality of life
opt.wrap = false              -- don't soft-wrap long lines
opt.scrolloff = 8             -- keep 8 lines of context above/below cursor
opt.clipboard = "unnamedplus" -- use OS clipboard for yank/paste by default
opt.undofile = true           -- persistent undo across sessions
opt.termguicolors = true      -- full-color terminal UI

-- Keymaps (leader key must be set before any <leader> mapping)
vim.g.mapleader = " "
vim.keymap.set("n", "<leader>w", ":w<CR>", { desc = "Save file" })
vim.keymap.set("n", "<leader>q", ":q<CR>", { desc = "Quit" })
vim.keymap.set("n", "<Esc>", ":nohlsearch<CR>", { desc = "Clear search highlight" })
vim.keymap.set("n", "<leader>e", ":Explore<CR>", { desc = "Open file explorer" })

7. Troubleshooting

Arrow keys or backspace act weird, or I see garbled characters. Your terminal emulator may not be sending proper terminal codes. Try a modern terminal (Windows Terminal, iTerm2, GNOME Terminal, Alacritty, Kitty) — old terminals like cmd.exe's legacy console are the usual culprit on Windows.

Colors look wrong or washed out. Set opt.termguicolors = true in your config and confirm your terminal emulator supports true color. Some SSH sessions or the default Windows console don't.

:w fails with "permission denied". You don't have write permission on the file. On Linux/macOS:

:w !sudo tee % > /dev/null

This writes the buffer via sudo without needing to restart Neovim as root.

I accidentally typed into the file instead of running a command. You were in Insert mode when you meant to be in Normal/Command mode. Press Esc, verify with : that a prompt appears at the bottom, then retry.

Undo isn't persisting between sessions. Add opt.undofile = true to your config. Neovim creates the undo directory automatically on first use, but a broken permissions setup can block it.

Clipboard yank/paste doesn't reach the OS clipboard. Run :checkhealth and look at the provider section — on Linux you need a clipboard tool installed (xclip, xsel, or wl-clipboard depending on X11/Wayland). macOS and Windows have it built in.

Neovim feels slow on startup. Run nvim --startuptime startup.log then open startup.log to see what's taking time. In a plugin-less setup this is rare but antivirus scanning on Windows can cause it.

"Swap file already exists" warning on open. Neovim crashed last time or the file is open elsewhere. Options: (R)ecover to restore unsaved changes, (D)elete if you're sure no other session has it open, or (Q)uit to inspect safely first with nvim -r filename.

Something seems broken and you don't know why. :checkhealth is the first command to run — Neovim's built-in self-diagnostic flags missing providers, config errors, and more, each with a suggested fix.

8. Quick Reference Card