How to make Vim settings permanent (your vimrc)

You switched on line numbers yesterday with :set number, and they were just what you wanted. This morning you opened Vim and they'd gone. Nothing broke. A :set changes the Vim you're typing in, and only until you quit. Every new Vim starts again from its defaults.

What Vim does at every start is run one file of yours, your config, called the vimrc. Each line in it is a command, as if you'd typed it after a colon, so a line that says set number turns the numbers on every time Vim opens.

Vim looks for these in your home folder, reads the first one it finds, and ignores the rest:

• ~/.vimrc
• ~/.vim/vimrc
• ~/.config/vim/vimrc, in recent versions, and only when neither of the others exists

On Windows the file is $HOME/_vimrc or $HOME/vimfiles/vimrc. Neovim reads ~/.config/nvim/init.vim or ~/.config/nvim/init.lua (on Windows, the same names in ~/AppData/Local/nvim/). Keep one or the other. With both, Neovim says E5422: Conflicting configs and loads only the Lua one.

You don't have to remember which. Vim keeps the path of the file it loaded in $MYVIMRC, so :echo $MYVIMRC prints it and :e $MYVIMRC opens it for editing, in Vim and Neovim alike.

If :echo $MYVIMRC prints an empty line, Vim found no config, so you make the file by its real path. In Vim, type :e ~/.vimrc, add your lines, and save with :w. In Neovim, type :e ~/.config/nvim/init.lua. The nvim folder may not exist yet, and then a plain :w fails with E212, so save the first time with :w ++p, which makes the folder too. From the next start on, $MYVIMRC points at your file.

In Vim, the moment a ~/.vimrc exists a few of its friendlier defaults switch off, syntax colours among them. Turn on syntax highlighting has the lines that bring them back.

Start with a few lines you understand rather than someone's whole file. These fix what most people notice in their first week:

• set number relativenumber numbers your line and shows how far away every other line is. Line numbers explains the pair.
• set tabstop=4 shiftwidth=4 expandtab indents with four spaces. Tab size has the two-space and real-tab versions.
• set ignorecase smartcase makes a search ignore case until you type a capital letter.
• set hlsearch incsearch lights up matches while you type a search and keeps them lit afterwards. :noh turns them off until your next search.
• inoremap jk <Esc> lets you leave Insert mode by typing j then k quickly.

A line starting with " is a comment, which is a good place to note why a line is there. The vimrc is a text file like any other, so you write it with the same keys you edit everything else with.

Saving the file changes nothing in the Vim you have open. It reads the vimrc when it starts, so either restart it or run the file yourself. :source % runs the file you're editing (% stands for its name), which makes it the thing to type right after :w in your vimrc. From any other file, :so $MYVIMRC does the same, :so being short for :source. Both work in Neovim, on init.lua too.

Reloading only adds settings. Delete the set hlsearch line, save, :source %, and the highlights stay on, because nothing in the file turns them off now. :set nohlsearch or a restart does that.

To see what a setting is right now, put a question mark after its name. :set hlsearch? answers hlsearch or nohlsearch, and :set tabstop? answers tabstop=4. When the answer isn't what your file says, :verbose set tabstop? also names the file and line that set it last, which is how you catch a plugin or a language's own settings changing yours.

A Vim line such as set number is a Lua error in init.lua ('=' expected near 'number'), and Neovim then runs none of the file. Each option is an assignment instead, where on and off are true and false and a number is just the number:

• vim.opt.number = true
• vim.opt.tabstop = 4
• vim.keymap.set("i", "jk", "<Esc>") for the j k mapping

To bring a Vim line across as it is, wrap it: vim.cmd("set ignorecase smartcase"). Or name the file init.vim instead, and every line from this page works there unchanged. Your Vim config, line by line puts the Vim and Lua spellings side by side and goes further into mappings and the leader key.