Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 36 ยท Configuration and Plugins

Your vimrc and Options

Create your Vim configuration file: where vimrc lives on Linux, macOS and Windows, how :set works, and the options almost everyone turns on, with explanations.

Vim starts almost plain, and that is deliberate: the configuration is yours. Everything you want to persist between sessions goes into one text file, the vimrc. In this lesson you find it, learn how :set works, and build a small but sensible set of options.

Where the file lives

Vim looks for a user configuration in this order and uses the first it finds:

System Typical paths
Linux, macOS ~/.vimrc, or ~/.vim/vimrc
Windows $HOME\_vimrc, $HOME\vimfiles\vimrc
Neovim (all systems) init.lua or init.vim in the config folder (see Neovim)

Inside Vim, :echo $MYVIMRC prints the path that was actually loaded, and :edit $MYVIMRC opens it. After you change the file, run :source % (or :so %) to apply it without restarting. Some settings, especially those depending on startup, may need a restart.

Vim 8.2 and later also read a built-in defaults.vim when no vimrc exists. As soon as you create your own vimrc, that file is skipped, so many people begin with source $VIMRUNTIME/defaults.vim on the first line and then override what they like.

How :set works

:set changes options. They come in three kinds: boolean (on or off), number and string.

VIM
set number          " turn a boolean on
set nonumber        " turn it off
set number!         " toggle
set number?         " ask the current value
set number&         " reset to default
set tabstop=4       " number option
set listchars=tab:>-,trail:~  " string option
set wildignore+=*.o " append to a list option

A " starts a comment. :setlocal sets an option only for the current buffer or window, and :set sets both the local value and the global default. To see where an option was last set, use :verbose set tabstop?.

Option names have short forms: nu for number, ts for tabstop, sw for shiftwidth. Prefer long names in a vimrc so it stays readable.

Options worth knowing

The following list is a good starting point. None of these change what you type, only how Vim helps you.

Display

  • number and relativenumber show line numbers; with both on the current line shows its absolute number and the others show distance, which makes 5j and d3k easy to aim.
  • cursorline highlights the current line; signcolumn=yes reserves room for markers so text does not jump.
  • scrolloff=8 keeps eight lines of context above and below the cursor.
  • wrap or nowrap; linebreak wraps at word boundaries.
  • termguicolors enables 24-bit colors in modern terminals; background=dark or light hints at the terminal theme.
  • laststatus=2 always shows the status line; showcmd shows pending keys.

Indentation

  • tabstop=4 is how wide a tab character looks.
  • shiftwidth=4 is the indent width for >>, << and auto-indent.
  • expandtab makes the Tab key insert spaces.
  • softtabstop=4 makes Tab and Backspace act in four-space steps.
  • autoindent copies indentation from the previous line; smartindent knows a bit about braces.

Searching

  • ignorecase with smartcase: case-insensitive unless the pattern has a capital letter.
  • incsearch jumps while you type; hlsearch highlights all matches (clear with :nohlsearch).

Behaviour

  • hidden lets you leave modified buffers (see Buffers).
  • mouse=a enables the mouse.
  • clipboard=unnamedplus uses the system clipboard for yanks and puts.
  • undofile keeps undo history on disk between sessions; undodir says where.
  • wildmenu shows completion candidates for Ex commands.
  • updatetime=300 makes CursorHold events and swap writes faster.
  • timeoutlen=500 is how long Vim waits for the next key of a mapping.
JS Stand-in: parse :set lines into settings

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

No output.

Three lines that help every vimrc

VIM
syntax on
filetype plugin indent on
set nocompatible

syntax on enables highlighting. filetype plugin indent on loads file-type specific settings, plugins and indent rules (a Python file gets Python indentation, for example). nocompatible is already the default for Vim 8 and Neovim, so you rarely need it today, but it appears in old guides and is harmless.

A starter file

VIM
" ~/.vimrc
set nocompatible
filetype plugin indent on
syntax on

set number relativenumber
set cursorline
set scrolloff=8
set signcolumn=yes

set tabstop=4 shiftwidth=4 softtabstop=4 expandtab
set autoindent

set ignorecase smartcase
set incsearch hlsearch

set hidden
set mouse=a
set undofile
set wildmenu
set updatetime=300

Save it, restart Vim, and check :set number? and :set shiftwidth?.

Keeping it healthy

  • Add one change at a time and test it. A vimrc grows by habit, so remove options you do not understand.
  • Use :verbose set option? to see who set a value; a plugin or a filetype file may have overridden your line.
  • If Vim misbehaves, start without your configuration to compare: vim -u NONE (no vimrc, no plugins) or vim --clean.
  • Keep the file in version control. A plain text vimrc is easy to share between machines.
  • File-type overrides do not belong in the main file: put setlocal shiftwidth=2 into ~/.vim/after/ftplugin/yaml.vim so it applies only to YAML buffers.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you apply a changed vimrc without restarting Vim?

    :source % (or :so %) runs the current file as Vim script. Some startup-only settings may still need a restart.
  2. 2. What does set number? do?

    A trailing ? queries the option, ! toggles it, & resets it, and no turns a boolean off.
  3. 3. Which option pair gives case-insensitive search unless you type an uppercase letter?

    ignorecase turns off case sensitivity; smartcase turns it back on when the pattern contains a capital.
  4. 4. How do you start Vim with no vimrc and no plugins to check a problem?

    vim -u NONE skips the vimrc; vim --clean also skips plugins and uses default settings.

Summary

  • Configuration lives in ~/.vimrc (or _vimrc on Windows, init.lua in Neovim); $MYVIMRC shows the real path.
  • :set has forms opt, noopt, opt!, opt?, opt&, opt=value and opt+=value.
  • Most people enable numbers, indentation settings, smart-case search, hidden, mouse and undofile.
  • Test with :source %, debug with :verbose and vim -u NONE.

Next: Mappings and the Leader Key