Vim Recipes ‣ Basics ‣ Configuring Vim

Configuring Vim

Problem

You want your Vim preferences to persist over sessions.

For example, you want Vim to show line numbers all the time. Displaying Line Numbers explains how, but when you restart Vim you find that your preferences have been forgotten.

Solution

Throughout this book I will discuss how to configure Vim options using the :set option or :set option=value syntax. This works, but only for the current instance of Vim. If you specify these options in your vimrc file they'll be set permanently.

Location of vimrc

The default location of the vimrc file depends on your operating system. Identify your operating system, then note the corresponding path. All references in this book to vimrc refer to this path.

Gvim reads vimrc then a gvimrc file located in the same place as vimrc. In this book vimrc and gvimrc are treated as synonyms.

Unix/Linux
$HOME/.vimrc
OS/2
$HOME/.vimrc or $VIM/.vimrc (or _vimrc)
MS-DOS and Windows
$HOME/_vimrc or $VIM/_vimrc
Amiga
s:.vimrc or $VIM/.vimrc

The vimrc is a simple plain text file. Open the filename specified in the sidebar and add one option per line using the option=value syntax (the ':' prefix is unnecessary). Indeed, this is the general principle for adding any Command-Line command in this book to your vimrc. For example:

" Set the boolean number option to true
set number
" Set the textwidth option to '78'
set textwidth=78
" Set the expandtab option to false
set noexpandtab

A single quotation mark (") introduces comments. They are ignored by Vim, but particularly useful for remembering what all of your preferences mean.

Even if you don't want to specify any options in vimrc you should still create it. On some systems Vim will act like the Vi editor in the absence of this file, which is unlikely to be what you want.

Discussion

The vimrc locations given in the sidebar are used for user preferences; there are also system wide vimrc files. User preferences take precedence over system preferences. This means that if you change an option set in the system vimrc, your preferences will be respected. However, if the system vimrc sets an option differently from the Vim defaults, and you don't include it in your vimrc, the system preference will be used.

The example vimrc above is very basic. They can also include functions, conditionals, and anything else Vim's scripting engine supports. For a simple example look at the usage of :autocmd in the Using Templates recipe.

If your configuration becomes complex you may want to split it over multiple files. You can instruct Vim to include these files in your configuration by adding a source file line to vimrc for each config file. See Abbreviating Common Strings for an example.

If you want a different configuration for a specific project you can :set exrc then include a .vimrc (or vimrc on DOS and MS Windows) in the project's directory. This takes precedence over your vimrc, and will be used when you edit files in that directory.

Warning: There's the potential for security problems when using exrc. If a vimrc was placed in your project directory without you knowing -- as a result of unpacking an archive, for example -- it could be used to execute arbitrary commands under your user account. For this reason it's strongly recommended that you use :set secure in conjunction with exrc. This prevents the directory-specific vimrc files from executing potentially dangerous commands. The Vim documentation suggests adding set secure as the last line in your vimrc.

Debugging Configuration